Difference between revisions of "Sip"

From HSYCO
Jump to navigation Jump to search
(Created page with "The HSYCO SIP I/O Server allows HSYCO to control standard VoIP client software (also called soft-phones), in order to integrate telephony features in HSYCO applications. Usin...")
 
 
(31 intermediate revisions by 2 users not shown)
Line 13: Line 13:
 
The current version of the SIP I/O Server has been tested with Linphone 3.5.2.
 
The current version of the SIP I/O Server has been tested with Linphone 3.5.2.
  
−
{{note|Linphone is a free software that you can use and distribute, currently licensed under the GNU GPL v2 license. You should verify with the Linphone owner that your intended use of this software is compliant with the license, or obtain a proprietary license of the software. Check [www.linphone.org] for additional information.}}
+
{{note|Linphone is a free software that you can use and distribute, currently licensed under the GNU GPL v2 license. You should verify with the Linphone owner that your intended use of this software is compliant with the license, or obtain a proprietary license of the software. Check [http://www.linphone.org www.linphone.org] for additional information.}}
  
 
=== Linphone Installation ===
 
=== Linphone Installation ===
Line 19: Line 19:
 
  sudo apt-get install linphone
 
  sudo apt-get install linphone
  
−
After the installation, run Linphone from the graphic desktop for the hsyco user, and configure the audio devices and levels. This configuration will be used when Linphone is run as a daemon process and called by HSYCO.
+
After the installation, run Linphone for the hsyco user, and configure the audio devices and levels. This configuration will be used when Linphone is run as a daemon process and called by HSYCO.
  
−
The ''hsycolinphone'' script must also be installed and executable ( The hsycolinphone script is installed in the /usr/local/bin directory).
+
The [[media:hsycolinphone.zip|hsycolinphone]] script file must be unzipped, copied in the /usr/local/bin/ folder and set as executable.
  
 
Finally, if you are using the the PulseAudio system, ensure that the user that will run Linphone is added to the pulse-access group, while if you are using the ALSA audio system, the user that will run Linphone should be added to the audio group instead.
 
Finally, if you are using the the PulseAudio system, ensure that the user that will run Linphone is added to the pulse-access group, while if you are using the ALSA audio system, the user that will run Linphone should be added to the audio group instead.
  
 
== HSYCO Configuration ==
 
== HSYCO Configuration ==
−
The VoIP client can be configured to work as a stand-alone client, or registered to a VoIP PBX system.
+
The VoIP client can be configured to work as a '''stand-alone client''', or '''registered to a VoIP PBX system'''.
  
 
You can define only one HSYCO SIP I/O Server in System Settings.
 
You can define only one HSYCO SIP I/O Server in System Settings.
 +
 +
Add a SIP I/O Server in the [[Settings#I/O Servers|I/O Servers section of the Settings]] and set its parameters:
 +
 +
=== Communication ===
 +
==== Stand-alone Client Configuration ====
 +
Leave all the communication parameters blank.
 +
 +
==== Registered Client Configuration ====
 +
*'''IP Address''': host name or IP address of the VoIP PBX system
 +
*'''IP Port''': TCP/IP port to use, leave blank to use default port 5060
 +
*'''User''': username for the PBX account you are using
 +
*'''Password''': password for the PBX account you are using.
 +
 +
=== High Availability ===
 +
*'''Shutdown when inactive''': defaults to true.
  
 
=== Options ===
 
=== Options ===
Line 57: Line 72:
 
|-
 
|-
  
−
|mode
+
|rowspan="2"|mode
 
|rowspan="2"|phone
 
|rowspan="2"|phone
 
|phone
 
|phone
Line 70: Line 85:
  
 
When Linphone is run on a remote system, HSYCO will use the SSH protocol to execute the remote call. The remote system should be configured to accept the SSH connection from the HSYCO server using the username and password defined in the I/O Server’s options.
 
When Linphone is run on a remote system, HSYCO will use the SSH protocol to execute the remote call. The remote system should be configured to accept the SSH connection from the HSYCO server using the username and password defined in the I/O Server’s options.
−
If you also need to control the display backlight or execute generic operating system’s commands, the remote user name defined with the user option in the SIP I/O Server configuration must be allowed to execute “sudo” commands without asking for a password. For example, if the user is hsyco, you could add the line:
+
 
 +
If you also need to control the display backlight or execute generic operating system’s commands, the remote user name defined with the user option in the SIP I/O Server configuration must be allowed to execute “sudo” commands without asking for a password.  
 +
 
 +
For example, if the user is hsyco, you could add the line:
 +
 
 
  hsyco  ALL=(ALL:ALL) NOPASSWD: ALL
 
  hsyco  ALL=(ALL:ALL) NOPASSWD: ALL
 +
 
at the end of the /etc/sudoers file (Use the visudo command to edit the /etc/sudoers file).
 
at the end of the /etc/sudoers file (Use the visudo command to edit the /etc/sudoers file).
  
 
== Datapoints ==
 
== Datapoints ==
−
 
−
{{note|the SIP protocol uses a standard URI format to identify the calling and called parties, like:
 
−
sip:user@host
 
−
where ''user'' is the username and ''host'' is the remote host name or IP address.}}
 
−
 
−
The SIP I/O Server will automatically remove or imply the “sip:” prefix from data-point values. @host will also be removed or implied if host is an exact match of the I/O Server IP parameter.
 
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 89: Line 103:
 
|-
 
|-
  
 +
|rowspan="2"|connection
 +
|online
 +
|R
 +
|connection established
 +
|-
 +
|offline
 +
|R
 +
|HSYCO can’t connect to the VoIP client application
 +
|-
 +
 +
|rowspan="2"|registration
 +
|0
 +
|R
 +
|the SIP client is not registered (note that this event is not guaranteed to reflect unregistration conditions caused by the SIP server)
 +
|-
 +
|1
 +
|R
 +
|the SIP client is registered to a SIP server
 +
|-
 +
 +
|rowspan="2"|mode
 +
|phone
 +
|R
 +
|the I/O Server is in phone mode
 +
|-
 +
|ivr
 +
|R
 +
|the I/O Server is in IVR mode
 +
|-
 +
 +
|rowspan="5"|call
 +
|rowspan="2" style="white-space:nowrap"|<SIP URI string>
 +
|R
 +
|a call is being established or is in progress with the remote party identified by the value of this data-point
 +
|-
 +
|W
 +
|start a call to a remote party
 +
|-
 +
|answer
 +
|W
 +
|answer an incoming call
 +
|-
 +
|hangup
 +
|W
 +
|hangup a call
 +
|-
 +
|<empty string>
 +
|R
 +
|no call is currently being established or in progress
 +
|-
 +
 +
|call.refused
 +
|<SIP URI string>
 +
|R
 +
|an incoming call is refused because another call is already in progress
 +
|-
 +
 +
|rowspan="4"|status
 +
|ring
 +
|R
 +
|receiving an incoming call, not yet answered
 +
|-
 +
|dial
 +
|R
 +
|dialing a call, not yet answered
 +
|-
 +
|active
 +
|R
 +
|incoming or outbound call in progress
 +
|-
 +
|hangup
 +
|R
 +
|no call is currently in progress
 +
|-
 +
 +
|transfer
 +
|<SIP URI string>
 +
|W
 +
|blind transfer an active or incoming call to a remote party
 +
|-
 +
 +
|rowspan="4"|mute
 +
|rowspan="2"|0
 +
|R
 +
|un-mute command sent successfully
 +
|-
 +
|W
 +
|un-mute the microphone
 +
|-
 +
|rowspan="2"|1
 +
|R
 +
|mute command sent successfully
 +
|-
 +
|W
 +
|mute the microphone (note that when a call is terminated, the mute status is reset)
 +
|-
 +
 +
|rowspan="4"|autoanswer
 +
|rowspan="2"|0
 +
|R
 +
|autoanswer is disabled
 +
|-
 +
|W
 +
|disable autoanswer mode
 +
|-
 +
|rowspan="2"|1
 +
|R
 +
|autoanswer is enabled
 +
|-
 +
|W
 +
|enable autoanswer mode
 +
|-
 +
 +
|rowspan="4"|volume
 +
|rowspan="2"|off
 +
|R
 +
|volume off command sent successfully
 +
|-
 +
|W
 +
|turn off the speaker
 +
|-
 +
|rowspan="2"|1 - 20
 +
|R
 +
|volume command sent successfully
 +
|-
 +
|W
 +
|set the speaker volume
 +
|-
 +
 +
|rowspan="2"|dtmf
 +
|rowspan="2"|0 - 9 # *
 +
|R
 +
|DTMF tone received
 +
|-
 +
|W
 +
|send DTMF tones (you can send one or more tones with the same command)
 +
|-
 +
 +
|generic
 +
|<string>
 +
|W
 +
|send a generic command to the Linphone application
 +
|-
 +
 +
|play.file
 +
|<filename>
 +
|W
 +
|only in IVR mode, play back a file to an active call. The file pathname must be relative to HSYCO’s root directory
 +
|-
 +
 +
|play.voice.<voice>
 +
|<text>
 +
|W
 +
|only in IVR mode, use the TTS engine to play back a text message, using the voice set with <voice>
 +
|-
 +
 +
|rowspan="4"|backlit
 +
|rowspan="2"|0
 +
|R
 +
|backlight off command sent successfully
 +
|-
 +
|W
 +
|turn off the display’s backlight
 +
|-
 +
|rowspan="2"|1
 +
|R
 +
|backlight on command sent successfully
 +
|-
 +
|W
 +
|turn on the display’s backlight
 +
|-
 +
 +
|exec
 +
|<command>
 +
|W
 +
|execute a generic operating system’s command
 +
|-
  
 
|}
 
|}
  
 +
{{note|The SIP protocol uses a standard URI format to identify the calling and called parties, like:
 +
<nowiki>sip:user@host</nowiki>
 +
where ''user'' is the username and ''host'' is the remote host name or IP address.}}
 +
 +
The SIP I/O Server will automatically remove or imply the <nowiki>“sip:”</nowiki> prefix from data-point values. @host will also be removed or implied if host is an exact match of the I/O Server IP parameter.
 +
 +
When an incoming call is ringing or an outbound call is being dialed, the SIP I/O Server also generates a PBX event and calls the PBXCallEvent() Java callback method. When the phone is ringing the event will be:
 +
 +
PBX <remote URI> = <local URI>
 +
 +
and the Java callback:
 +
 +
PBXCallEvent(“<ID>”, “<remote URI>”, “<local URI>”)
 +
 +
When an outbound call is established, the event will be:
 +
 +
PBX <local URI>  = <remote URI>
 +
 +
and the Java callback:
 +
 +
PBXCallEvent(“<ID>”, “<local URI>”, “<remote URI>”)
 +
 +
{{tip|Note that, if the SIP I/O Server is configured as a stand-alone client, the <local URI> is replaced with the I/O Server’s ID.}}
  
 
== Release Notes ==
 
== Release Notes ==
 +
=== 3.5.1 ===
 +
*improved compatibility with latest versions of linphone
 
=== 3.3.0 ===
 
=== 3.3.0 ===
 
*improved performance of the SSH connection to remote servers
 
*improved performance of the SSH connection to remote servers

Latest revision as of 16:56, 15 March 2016

The HSYCO SIP I/O Server allows HSYCO to control standard VoIP client software (also called soft-phones), in order to integrate telephony features in HSYCO applications.

Using the SIP I/O Server, you will be able to use the audio capabilities of the HSYCO Server to implement a speakerphone with all calling features being controlled by HSYCO itself. This “phone” mode is particularly useful when HSYCO is running on a touch screen equipped with a microphone and speaker, and a kiosk mode Web browser, to create customized door-entry control panels with audio/video capabilities.

The SIP I/O Server also works as a basic IVR (interactive voice response) system, allowing HSYCO to interact with users via the standard telephony system through the use of voice and DTMF tones input on the phone’s keypad.

VoIP Applications

The SIP I/O Server currently works with the Linphone Voice Over IP software phone, on Linux systems only. Linphone must be installed and properly configured on the Linux system that runs the HSYCO Server.

The current version of the SIP I/O Server has been tested with Linphone 3.5.2.

Linphone is a free software that you can use and distribute, currently licensed under the GNU GPL v2 license. You should verify with the Linphone owner that your intended use of this software is compliant with the license, or obtain a proprietary license of the software. Check www.linphone.org for additional information.


Linphone Installation

From the Linux command-line shell, install the software with the command: 

sudo apt-get install linphone

After the installation, run Linphone for the hsyco user, and configure the audio devices and levels. This configuration will be used when Linphone is run as a daemon process and called by HSYCO.

The hsycolinphone script file must be unzipped, copied in the /usr/local/bin/ folder and set as executable.

Finally, if you are using the the PulseAudio system, ensure that the user that will run Linphone is added to the pulse-access group, while if you are using the ALSA audio system, the user that will run Linphone should be added to the audio group instead.

HSYCO Configuration

The VoIP client can be configured to work as a stand-alone client, or registered to a VoIP PBX system.

You can define only one HSYCO SIP I/O Server in System Settings.

Add a SIP I/O Server in the I/O Servers section of the Settings and set its parameters:

Communication

Stand-alone Client Configuration

Leave all the communication parameters blank.

Registered Client Configuration

  • IP Address: host name or IP address of the VoIP PBX system
  • IP Port: TCP/IP port to use, leave blank to use default port 5060
  • User: username for the PBX account you are using
  • Password: password for the PBX account you are using.

High Availability

  • Shutdown when inactive: defaults to true.

Options

ID Default Values Description
user hsyco username the operating system’s user name that will be used to run the Linphone application, either locally or on a remote server
host remote host name or address the hostname or IP address of the remote server where Linphone is installed
password password this option is required when host is defined. It is the password for the remote user
mode phone phone phone mode
ivr ivr mode

Remote System Configuration

When Linphone is run on a remote system, HSYCO will use the SSH protocol to execute the remote call. The remote system should be configured to accept the SSH connection from the HSYCO server using the username and password defined in the I/O Server’s options.

If you also need to control the display backlight or execute generic operating system’s commands, the remote user name defined with the user option in the SIP I/O Server configuration must be allowed to execute “sudo” commands without asking for a password.

For example, if the user is hsyco, you could add the line: 

hsyco   ALL=(ALL:ALL) NOPASSWD: ALL

at the end of the /etc/sudoers file (Use the visudo command to edit the /etc/sudoers file).

Datapoints

ID Value R/W Description
connection online R connection established
offline R HSYCO can’t connect to the VoIP client application
registration 0 R the SIP client is not registered (note that this event is not guaranteed to reflect unregistration conditions caused by the SIP server)
1 R the SIP client is registered to a SIP server
mode phone R the I/O Server is in phone mode
ivr R the I/O Server is in IVR mode
call <SIP URI string> R a call is being established or is in progress with the remote party identified by the value of this data-point
W start a call to a remote party
answer W answer an incoming call
hangup W hangup a call
<empty string> R no call is currently being established or in progress
call.refused <SIP URI string> R an incoming call is refused because another call is already in progress
status ring R receiving an incoming call, not yet answered
dial R dialing a call, not yet answered
active R incoming or outbound call in progress
hangup R no call is currently in progress
transfer <SIP URI string> W blind transfer an active or incoming call to a remote party
mute 0 R un-mute command sent successfully
W un-mute the microphone
1 R mute command sent successfully
W mute the microphone (note that when a call is terminated, the mute status is reset)
autoanswer 0 R autoanswer is disabled
W disable autoanswer mode
1 R autoanswer is enabled
W enable autoanswer mode
volume off R volume off command sent successfully
W turn off the speaker
1 - 20 R volume command sent successfully
W set the speaker volume
dtmf 0 - 9 # * R DTMF tone received
W send DTMF tones (you can send one or more tones with the same command)
generic <string> W send a generic command to the Linphone application
play.file <filename> W only in IVR mode, play back a file to an active call. The file pathname must be relative to HSYCO’s root directory
play.voice.<voice> <text> W only in IVR mode, use the TTS engine to play back a text message, using the voice set with <voice>
backlit 0 R backlight off command sent successfully
W turn off the display’s backlight
1 R backlight on command sent successfully
W turn on the display’s backlight
exec <command> W execute a generic operating system’s command
The SIP protocol uses a standard URI format to identify the calling and called parties, like: 
sip:user@host
where user is the username and host is the remote host name or IP address.


The SIP I/O Server will automatically remove or imply the “sip:” prefix from data-point values. @host will also be removed or implied if host is an exact match of the I/O Server IP parameter.

When an incoming call is ringing or an outbound call is being dialed, the SIP I/O Server also generates a PBX event and calls the PBXCallEvent() Java callback method. When the phone is ringing the event will be: 

PBX <remote URI> = <local URI>

and the Java callback: 

PBXCallEvent(“<ID>”, “<remote URI>”, “<local URI>”)

When an outbound call is established, the event will be: 

PBX <local URI>  = <remote URI>

and the Java callback: 

PBXCallEvent(“<ID>”, “<local URI>”, “<remote URI>”)

Note Note that, if the SIP I/O Server is configured as a stand-alone client, the <local URI> is replaced with the I/O Server’s ID.

Release Notes

3.5.1

  • improved compatibility with latest versions of linphone

3.3.0

  • improved performance of the SSH connection to remote servers
  • support of password-based authentication

3.2.1

  • text-to-speech performance improvements

3.2.0

  • initial release
Retrieved from "https://wiki.hsyco.com/3.8/index.php?title=Sip&oldid=6358"