README

Yeaphone - a SIP phone for Yealink USB-P1K handsets using liblinphone
========
(c) Copyright 2006-2008 by Thomas Reitmayr <treitmayr@devbase.at>
Homepage: http://www.devbase.at/
Released under the GNU GENERAL PUBLIC LICENSE v2 or later

The goal of the Yeaphone project is to provide a user interface on a
Yealink USB handset <http://www.yealink.com/en/index.asp> for the VoIP
software Linphone thus making a PC keyboard and monitor unneccessary.
This makes Yeaphone ideal for "Embedded Devices" which work very energy
efficient but typically need an extra devices for user interaction (in
this case the handset). Parts of the following description emphasizes
on the Linksys NSLU2 but the software should work on many Linux-based
embedded and PC systems.

"But why not buy one of the commercially available VoIP phones?", you
might ask. A few advantages and disadvantages about using Yeaphone on an
NSLU2 I can think of are:

    + The additional costs for NSLU2 owners are relatively low, about
      30 Euro for a Yealink P1K.
    + No need for an additional box most likely requiring an additional
      power supply.
    + In parallel to Yeaphone one can install an Asterisk server on the
      same box to get features like extensions, configurable answering
      machine, individual dial plans, call lists.

    - Rather complex procedures for installing the SlugOS firmware and
      the applications. Therefore the use on an NSLU2 is recommended for
      experienced Linux users only.
    - Possible interruptions of calls at high network or CPU loads, eg.
      when massivly accessing connected harddrives or other installed
      services while being on the phone. Note: QoS is not a Yeaphone-
      specific issue.


Features
========

    * Display the phone number of incoming and outgoing calls
    * Show the duration of a call
    * Allows to store and recall 10 phone numbers
    * Individual ring tones
    * Mute the ring tone of incoming calls
    * Adjustable volume of the speaker
    * and more ... 


Download & Installation
=======================

Please check the devbase.at website for availability of binary packages
for your architecture. There you can also find a tar-ball of the latest
release of the Yeaphone source code as well as instructions how to
access the Subversion repository.


Configuration
=============

Yeaphone has to be configured through linphonec, the console version
of Linphone. The following example shows how to get a working connection
to a VoIP provider.

root@NSLU2:~# linphonec
Ready
linphonec> soundcard list
0: ALSA: default device
1: ALSA: USB Audio
2: ALSA: VOIP USB Phone
3: OSS: /dev/dsp
4: OSS: /dev/dsp1
linphonec> soundcard use 2
Using sound device ALSA: VOIP USB Phone
linphonec> proxy add
Adding new proxy setup. Hit ^D to abort.
Enter proxy sip address: sip:sipgate.at
Your identity for this proxy: sip:1234567@sipgate.at
Do you want to register on this proxy (yes/no): yes
Specify register expiration time in seconds (default is 600): 600
Expiration: 600 seconds
Specify route if needed: [leave empty]
No route specified.
--------------------------------------------
sip address: sip:sipgate.at
route:
identity: sip:1234567@sipgate.at
register: yes
expires: 600
--------------------------------------------
Accept the above proxy configuration (yes/no) ?: yes
Proxy added.
linphonec>
Password for 1234567 on "sipgate.at": [enter password]
Registration on sip:sipgate.at sucessful.
linphonec>

Using linphonec the VoIP connection can be tested immediately before
using Yeaphone. The speaker and microphone of the Yealink handset can be
used already, commands still have to be entered through the PC keyboard
though. The most important commands of linphonec are:

    * help [<command>]
      shows the available commands and provides a detailed description
      for each command
    * call <phone number or SIP address>
      dials the specified phone number of SIP address
    * answer
      answers an incoming call
    * terminate
      terminates an (incoming or outgoing) call
    * quit
      unregisters at the VoIP provider and quits linphonec

As soon as calls can be make this way, linphonec can be stopped and
yeaphone can be invoked. Its output should look similar to this:

root@NSLU2:~# yeaphone
path_sysfs = /sys/bus/usb/drivers/yealink/3-1.3:1.3/
path_event = /dev/input/event2
Ready
Registration on sip:sipgate.at sucessful.

At the same time the current date and time are show on the handset's
display, a quick sequence of status messages appears, and finally the
lower part of the display should be cleared. Now the handset's keyboard
can be used to place and receive calls.

The various keys have the following functions:

   1. before a phone call
          * 0-9,*,#
            Dial a phone number
          * C
            Remove the last character of the dialed number
          * C pressed long
            Remove the complete number
          * <red key>
            Remove the complete number
          * <green key>
            Initiate the call
          * <up key> + <0-9>
            No number dialed yet: Recall and display a number from
            memory X
            Number already dialed: Store the currently displayed number
            at memory X
   2. during a phone call
          * 0-9,*,#
            Generate DTMF tones
          * <red key>
            Terminate the call
          * VOL+/-
            Adjust the speaker's volume 
   3. after a phone call (with the last number displayed)
          * 0-9
            Dial a new phone number
          * C
            Remove the complete number
          * <red key>
            Remove the complete number
          * <green key>
            Redial the last number
          * <up key> + <0-9>
            Store the last number to memory /X/ 
   4. when the phone rings
          * #
            Mute the ringing without picking up
          * <red key>
            Immediately terminate the call without picking up
          * <green key>
            Pick up 
   5. general
          * <red key> pressed long
            Start and stop the VoIP connection (corresponds to turning
            on/off a phone) 

To correctly understand the phone number of incoming calls, Yeaphone
needs some adjustments in the file ~/.yeaphonerc. After terminating
yeaphone the parameters intl-access-code, natl-access-code, and
country-code should be changed accordingly, the default values work for
Austria only.

In ~/.yeaphonerc you can also spedify custom ringtones for different
numbers by adding lines according to the following example:
  ringtone_default   /usr/share/yeaphone/ringtones/default_p1k.bin
  ringtone_01234567  /usr/share/yeaphone/ringtones/special_p1k.bin
  ringtone_0555777   doorbell_p1k.bin

If you specify relative paths to the ringtones, they are based on
$HOME/.yeaphone/ringtone.

Another feature to be configured in ~/.yeaphonerc is the minimum ring
duration. If for a certain caller ID the duration of the ring should be at
least 5 seconds, this can be specified as:
  minring_01234567  5

For security reasons Yeaphone should not be run as user "root". You
could create a new group called "voip" on your system and make sure that
this group is allowed to access the yealink driver interface.
Example for a udev rule (in file /etc/udev/rules.d/99-yealink.rules):
KERNEL=="event*", DRIVERS=="yealink", GROUP="users", RUN+="/bin/sh -c '/bin/chgrp users /sys$env{PHYSDEVPATH}/*'"


Disclaimer
==========
The authors do not take any responsibility for problems and damage
arising by installing or using this software, use it at your own risk.