View source for AlphaCom SIP interface

== SIPd Overview ==
The SIPd is a signalling gateway. It handles call setup and termination requests and does the necessary conversions between the AlphaNet and [[SIP]] protocols.

The SIPd runs on the AMC IP. It is connected to one AlphaCom running on the same AMC IP. All requests from AMC stations are received via this AlphaCom node.

The intended usage of SIPd is that it forwards calls to and from SIP phones. SIP phones may be controlled by an external SIP proxy server, such as Cisco Call Manager. Or to interface to POTS or ISDN telephone systems via a SIP gateway.

For sites that do not have a separate SIP proxy server, it is possible to connect the SIP phones directly to
SIPd.

Once a call is established, the RTP media flows directly between the AlphaCom and the SIP phones, without any involvement from SIPd.

== Function ==
=== Overview ===
The SIPd is configured as a collection of one or more virtual AlphaNet nodes.

Each virtual AlphaNet node gives the IP address of a SIP device. The SIP device can be a SIP proxy server, in turn handling a number of SIP phones. Or it can be one single SIP phone. AlphaCom does not really care about the difference.

SIPd can also act a registrar and proxy server for SIP phones. In that case the IP address of the virtual AlphaNet node is set to be the same as the hosting AlphaCom. The directory numbers of the SIP phones are entered into AlphaPro as remote AlphaNet numbers pointing to the Registar node. SIPd will accept registrations from stations with number found in this list of directory numbers. The IP address and UDP port of the station is stored in a database.

Call setups from AlphaNet nodes are targeted towards one of the virtual AlphaNet nodes. This is performed in two steps:

# The AlphaCom looks up the dialled number and finds the destination and link node in its Directory Table and Data Routing Table.
# The SIPd looks up the configuration for that Virtual node
: a. If the node is set up as proxy/registrar, look up the IP address and UDP port of the phone in the registrar base
: b. Otherwise use the IP address of the target SIP proxy in its Virtual Node Table. 

=== Configuration handling ===
The SIPd Virtual Node Table is configured via AlphaPro

Corresponding number series and node definitions must be configured in the AlphaCom Directory Table and Data Routing Table by using AlphaPro. AMCD transfers the configuration relevant to SIPd in a text file, /tmp/sipd_config.

=== Calls ===
The SIPd supports 32 simultaneous calls.

The SIPd only supports audio calls.

SIPd supports SIP phones with auto-answer (results in different SIP signalling with no 180 Ringing messsages).

3 examples of SIP phones tested successfully with SIPd:

* SIP phone terminals (e.g. Grandstream BudgeTone 100)

* Analog phones connected to a SIP analog/SIP adapter (e.g. Grandstream HandyTone)

* SIP softphones (e.g. X-Lite)

==== Codec negotiation ====
The SIPd is responsible for codec negotiation. It analyses the codec lists received in the AlphaNet messages
and the SDP payload from the SIP messages. If a codec match is found, the call is established, otherwise it
is terminated.

The SDP protocol only describes codec capabilities. It is really not a negotiation protocol. SDP allows SIP phones to use any matching codec. However, the SIPd will always pick one and only one codec, which is the
first matching codec in the codec lists.

Note! SIP phones that do not use the first matching codec from the codec lists are not supported by SIPd. The AlphaCom can be configured to only send one codec in its codec list. Then this problem will not occur.

==== Overlapped dialling ====
In SIP, overlapped dialling means that each digit is forwarded as the user dials it.
SIPd supports overlapped dialling. Single digits can be sent and received using the SIP INFO method. Digit transport in RTP (RFC2833) is currently not supported.

The AlphaCom can also be configured to handle the collection of all digits dialled from an AMC station, and waits until it is complete before forwarding the call to SIPd.

=== Logging ===
==== trace and debug ====

The SIPd offers runtime trace and debug logging via the [[Linux Console]]. This is intended for debug and on-site trouble shooting.

The trace-interface is found as an internal unix-socket in AMC: “/tmp/sipd_trace”. Log in via telnet (user: alpha; password: com), and type:

 tst -s /tmp/sipd_trace

A few simple input commands are implemented, type single letters;

<pre>
 0,1,2,3,4,5,6,7: Set tracelevel.
       0: Fatal errors only
       4: SIP/AlphaNet message trace (default)
       7: All internal debug trace also
  l:  list active calls
  h:  This text
</pre>

== SIP protocol operation ==
Consult RFC 3261 for description of SIP, and RFC 4566 on SDP. (http://tools.ietf.org/html/rfc3261 / http://tools.ietf.org/html/rfc4566 ). Important concepts as SIP transactions, Cseq, SIP dialog and SIP call-ID should be looked up here.

This chapter comments on how AlphaCom supports SIP, and about limitations.
  
First some general comments.

SIP Transport: SIPd supports only SIP over UDP, and receives only on UDP port 5060.

SIP URI usage: SIPd assumes the user part of URIs specify a phone/directory number.

SIPd does currently not support domain names in SIP URIs  (AlphaCom does not contain a DNS resolver).

SIPd currently ignores SIP responses not related to INVITE.

=== REGISTER ===
Example of an REGISTER transaction from a SIP phone with address 169.254.1.101.
<pre>
REGISTER sip:169.254.1.5 SIP/2.0
Via: SIP/2.0/UDP 169.254.1.101:62952;branch=z9hG4bK15fdffffcbd50000
From: <"Smith, J" sip:52304@169.254.1.5;user=phone>;tag=093400009879ffff
To: <sip:52304@169.254.1.5;user=phone>
Contact: <sip:52304@169.254.1.101:62952;user=phone>
Call-ID: 5099ffffa1ccffff@169.254.1.101
CSeq: 260 REGISTER
Expires: 3600
User-Agent: ImaginarySoft ImaginaryPhone 0.0.0.1
Max-Forwards: 70
Allow: INVITE,ACK,CANCEL,BYE,NOTIFY,REFER,OPTIONS,INFO,SUBSCRIBE
Content-Length: 0
</pre>
The important header fields are To: and Contact:

The To: header must match a directory number defined in the AlphaCom. The user-name part of the SIP URI (before @)
must be equal to the directory number in question.

The Contact: header gives the addess where the phone can receive calls. ”:62952” in this example is the UDP port used
by this SIP UserAgent. SIPd (since version 01.02) handles registrations from any UPD port. If the port number is not
present in the URI, default SIP port 5060 is assumed.

A * in the Contact list will remove the binding for that user.

SIPd can only store one contact address for each user. The last Register message overwrites earlier contact addresses
for that user.

Immediate response will be a  ”100 Trying” message.

Successful registration will give a ”200 OK message”
<pre>
SIP/2.0 200 OK
Via: SIP/2.0/UDP 169.254.1.101:62952;branch=z9hG4bK15fdffffcbd50000
From: "Smith, J" <sip:52304@169.254.1.5;user=phone>;tag=093400009879ffff
To: <sip:52304@169.254.1.5;user=phone>
Call-ID: 5099ffffa1ccffff@169.254.1.101
CSeq: 260 REGISTER
Contact: <sip:52304@169.254.1.101:62952;user=phone>
Allow: INVITE, ACK, REGISTER, BYE, CANCEL, INFO
Content-Length: 0
</pre>
Unsuccessfull registrations may return

* “404 NOT FOUND” if the request was legal, but the number in the To: URI did not match a directory number.

* “400 BAD REQUEST” if SIP could not parse the To: header

=== INVITE, incoming to SIPd / AlphaCom ===

Example of the phone sending INVITE
<pre>
INVITE sip:104@169.254.1.5;user=phone SIP/2.0
Via: SIP/2.0/UDP 169.254.1.101:62952;branch= z9hG4bKc61400003a3bffff
From: "Smith, J" <sip:52304@169.254.1.5;user=phone>;tag= f64fffff13050000
To: <sip:104@169.254.1.5;user=phone>
Contact: <sip:169.254.1.101:62952;user=phone>
Supported: replaces
Call-ID: cbc00000b21bffff@169.254.1.101
CSeq: 32627 INVITE
User-Agent: ImaginarySoft ImaginaryPhone 0.0.0.1
Max-Forwards: 70
Allow: INVITE,ACK,CANCEL,BYE,NOTIFY,REFER,OPTIONS,INFO,SUBSCRIBE
Content-Type: application/sdp
Content-Length: 154

v=0
o=52304 8000 8000 IN IP4 169.254.1.101
s=SIP Call
c=IN IP4 169.254.1.101
t=0 0
m=audio 5004 RTP/AVP 0
a=sendrecv
a=rtpmap:0 PCMU/8000
a=ptime:20
</pre>

The user part of the To: header field specifies the directory number of station to be called in AlphaCom (Here: number “104” ).

The information in the From: header is presented on the display of the called station in AlphaCom. The user name must contain digits only, and is presented as the calling number (52304), and the “display name” is presented as the name of the caller. Display name should be quoted in “”, and contents encoded in UTF-8.

CSeq and Call-ID must be set according to RFC.
Regarding the SDP media description: The c=, m= and a= fields are the one used by SIPd.  

The IP address for the RTP data is found in c=. It need not be the same as the IP address used by SIP.

The UDP port is the number following “audio” in m=. The RTP payload type is specified in last parameter in m=. AlphaCom only handles three of the static RTP payloadtypes in RFC 3551:

* 0: PCMU
* 8: PCMA
* 9: G722

Dynamic RTP payload types are currently not supported by AlphaCom. a=rtpmap field is therefore not really necessary
for AlphaCom.

If the INVITE is valid, SIPd will respond immediately with a 200 OK message, which completes the RTP setup.

The SIP connection is established immediately with a 200 OK, even if connection is not completed to the final
destination in AlphaCom. Particularly, SIPd does currently not transmit 180 Ringing status, you only hear the ringing
tone in the audio. Also, call to a busy station will result in connection to a busy tone audio signal, no 485 Busy
here. Failure/busy tones will be followed by a BYE from AlphaCom. These are limitations of current version, which may
be changed later.

Here is the 200 OK message from the example. The most important fields here are c= and m= which gives the IP address
and port for the AlphaCom end of the RTP connection.
<pre>
SIP/2.0 200 OK
Via: SIP/2.0/UDP 169.254.1.101:62952;branch=z9hG4bK9c5fffff2fe20000
From: "Smith, J" <sip:52304@169.254.1.5;user=phone>;tag= f64fffff13050000
To: <sip:104@169.254.1.5;user=phone>;tag=2076924972
Call-ID: cbc00000b21bffff@169.254.1.101
CSeq: 32627 INVITE
Contact: "Brown, B" <sip:104@169.254.1.5:5060>
Allow: INVITE, ACK, REGISTER, BYE, CANCEL, INFO
Content-Type: application/sdp
Content-Length:   134

v=0
o=Brown 20000001 20000001 IN IP4 169.254.1.5
s=-
c=IN IP4 169.254.1.5
t=0 0
m=audio 61000 RTP/AVP 0
a=rtpmap:0 PCMU/8000
</pre>

=== INVITE, outgoing from SIPd / AlphaCom ===
<pre>
INVITE sip:52304@169.254.1.101 SIP/2.0
Via: SIP/2.0/UDP 169.254.1.5:5060;branch=z9hG4bK256554362
From: "Brown    " <sip:104@169.254.1.5>;tag=1650601524
To: <sip:52304@169.254.1.101 >
Call-ID: 654880700@169.254.1.5
CSeq: 70335 INVITE
Contact: <sip:104@169.254.1.5:5060>
Max-Forwards: 70
User-Agent: AlphaSip gateway
Subject: Forwarding AlphaCom call
Expires: 120
Allow: INVITE, REGISTER, ACK, BYE, CANCEL, INFO
Content-Type: application/sdp
Content-Length:   136

v=0
o=Brown 20000001 20000001 IN IP4 169.254.1.5
s=-
c=IN IP4 169.254.1.5
t=0 0
m=audio 61000 RTP/AVP 0
a=rtpmap:0 PCMU/8000
</pre>
The From: header contains the name and directory number of the calling AlphaCom station.

Otherwise the same comments as on the incoming INVITE applies here.

SIPd handles 180 ringing status, sets out ringing tone to calling station. 200 OK message is expected to complete the RTP setup. “486 Busy here” and “600 busy everywhere” will setup busy tone to the calling station, and the AlphaCom will retry the setup a few times.   All other status responses >= 300 will terminate the call with a failure tone. No handling of redirects etc.

=== INFO, digits in call ===
SIP INFO messages can be used to send and receive single digits dialled during a call. 

AlphaCom will send INFO digit messages in a outgoing call when the calling user presses digit keys on the station during the call. DAK keys are used to dial DTMF signals above 9. * = DAK0, # = DAK1 (upper DAK keys, and are labeled * and # on many stations). From AMC version 10.31, DTMF codes A, B, C and D can be dialled by DAK keys 2 to 5.

AlphaCom can receive INFO digits in both incoming and outgoing calls. The handling of the digits will depend on the context, in the same way as dialling from an internal AlphaCom station. * is handled as M-pres, and # as M-release.

Example of an outgoing INFO digit message:
<pre>
INFO sip:52304@169.254.1.101;user=phone SIP/2.0
Via: SIP/2.0/UDP 169.254.1.5:5060;branch=z9hG4bK758154553
From: "Brown" <sip:104@169.254.1.5>;tag=290610420
To: <sip:52304@169.254.1.101>;tag=10570000a80cffff
Call-ID: 1097021121@169.254.1.5
CSeq: 70337 INFO
Contact: <sip:104@169.254.1.5:5060>
Max-Forwards: 70
User-Agent: AlphaSip gateway
Content-Type: application/dtmf-relay
Content-Length:    22

Signal=5
Duration=250
</pre>

The format expected in incoming INFO messages is similar.

“Signal” denote the key pressed. Only one single key can be transmitted or received with each message. Ordinary digits are
encoded as a single letter 0 – 9. * and # are encoded as the letters * and # (from verision 01.04). In incoming
messages, “Signal=*” and  “Signal=10” can be used for *,   “Signal=#” and  “Signal=11” can be used for #. DTMF digits ABCD is codes as the letters ABCD (from SIPD version 01.13). 

Duration is hardcoded to 250 (ms) in outgoing messages, and is ignored for incoming messages.

== SIPd Responses==
Explanation of what went wrong for selected non-successful SIP responses. ''Very incomplete ...''  

* 400 BAD_REQUEST : Incoming INVITE: Missing To or From URLs, or missing m= lines in SDP part
* 403 FORBIDDEN : Incoming INVITE: Validation of From: SIP header failed. Invite is accepted if 
** user part of from-URL matches a registrated user, or
** IP address of from-URL matches a configued "SIP trunk".

*503 SERVICE_UNAVAILABLE : Failed to allocate internal data structure 

[[Category:AlphaCom E Software]]
[[Category:SIP]]
[[Category: Troubleshooting]]



== Limitations ==
''Very very incomplete ...''

* Early media not supported (SDP in 1xx responses)
* Late SDP offer not supported (INVITE with no SDP)
* Redirection of outgoing INVITE not supported