Difference between revisions of "AlphaCom SIP interface"
From Zenitel Wiki
(→Digits in call) |
|||
| (47 intermediate revisions by 5 users not shown) | |||
| Line 1: | Line 1: | ||
| + | {{AI}} | ||
== SIPd Overview == | == SIPd Overview == | ||
| − | The SIPd is a | + | The SIPd is a signaling gateway. It handles call setup and termination requests and does the necessary conversions between the AlphaNet and [[SIP]] protocols. |
| − | The SIPd | + | The SIPd is an internal process running in the ICX-500 or the AMC-IP board (AlphaCom). It is connected to the ICX-AlphaCom or AlphaCom running on the same device. All requests from Zenitel devices are received via the ICX-AlphaCom node. The RTP media flows directly between the RtpDaemon and the SIP phones, without any involvement from SIPd. |
| − | + | SIP interfacing in ICX-AlphaCom is configured in AlphaPro. | |
| − | + | A SIP device can be used with ICX-AlphaCom in one of two different modes: | |
| − | + | * SIP trunk | |
| + | * SIP as station | ||
| − | + | Both modes can be used in ICX-AlphaCom simultaneously, but a given SIP device can only be configured for use in one mode in ICX-AlphaCom | |
| − | == | + | == Operating modes== |
| − | === | + | === SIP Trunk=== |
| − | + | Trunked mode is intended for connection to an external system with many telephones, it may be a SIP proxy, a SIP PBX or a PSTN gateway to mention a few. Use this mode if ICX-AlphaCom only should know about the SIP proxy/PBX/gateway, not about the individual telephones. It is technically possible to connect a single SIP phone as a trunk, but it is usually better to connect single telephones as "SIP station", see below. | |
| + | |||
| + | ICX-AlphaCom allow multiple conversations to a SIP trunk. The number of simultaneous conversations are limited by: | ||
| + | * the license: [[Licenses for ICX-500 and ICX-AlphaCom Core]] or [[Licenses#SIP_trunk_license|SIP trunk license in AlphaCom]] | ||
| + | * the availability of VoIP channels or the optional configuration of maximum number of lines used for each trunk | ||
| − | + | The "ICX-AlphaCom" restriction for number of lines for each trunk is configurable from AlphaPro and from the Billing web trunk menu. (or TST->nvram) <br> | |
| + | If maximum number of simultaneous conversations is reached (max lines configured for each trunk or available licenses): | ||
| + | * Calling attempt by users with high setup priority will break down an existing call with lower priority to free a trunk link. | ||
| + | * Calling attempt by users with same or lower setup priority will start camping for a free link, Camp tone and "Busy" in the display. | ||
| + | |||
| + | In a system where the number of simultaneous lines supported in the external system is less that the ICX-AlphaCom restrictions, when calling from ICX-AlphaCom to SIP trunk, you only get busy tone if the SIP equipment responded with a ''busy'' SIP response code (486, 600). | ||
| − | + | When calling from an ICX-AlphaCom station to a SIP trunk, the user will usually dial additional digits to address the actual telephone. This may be done in two different ways: | |
| + | * The access number to the trunk is configured so that ICX-AlphaCom (AMCD) will collect a number of digits, before sending a INVITE with the complete number. | ||
| + | * The access number to the trunk is configured so that ICX-AlphaCom immediately connects to the proxy/PBX/gateway, and subsequent digits are forwarded as [[#Digits in call]]. | ||
| − | + | ICX-AlphaCom will accept incoming call from anywhere (no restriction on SIP.From:), as long as the last hop of the call is via the proxy/PBX/gateway configured for the trunk. | |
| − | + | A SIP Trunk is configured as a virtual AlphaNet [[Node]] with the "exchange_class" set to SIP. | |
| − | |||
| − | |||
| − | |||
| − | + | To configure access numbers to the trunk for outward dialing, use [[Call remote exchange feature]] or [[Call remote station feature]]. It the access number itself should be included in the outgoing INVITE, use the latter. Either way use "param2" if ICX-AlphaCom should collect more digits before sending INVITE. | |
| − | |||
| − | + | The SIP routing of SIP trunk node can be configured in two different ways: | |
| + | * Configured IP address | ||
| + | * Registrar mode | ||
| − | === | + | ==== Fixed IP address ==== |
| − | + | In this case the IP address of the SIP device is configured in AlphaPro. It is only possible to configure one single address. It is possible to enter a hostname, if the IP address of the hostname is configured in [[AlphaWeb#Hostnames]]. | |
| − | + | ==== UDP Port ==== | |
| + | It is possible to configure the UDP port from default SIP UDP port 5060. Thus must be done in the nvram:<br> | ||
| + | {{Code|.ex_profile.ip_config.sip_data <nowiki>=</nowiki> 5060}} | ||
| + | This is best done using an event: | ||
| + | [[File:SIP udp.png|thumb|left|750px]] | ||
| + | <br style="clear:both;" /> | ||
| − | + | The port in the [[ICX_Web#Filters|firewall]] must also be changed. | |
| − | + | When calling from ICX-AlphaCom to the trunk, ICX-AlphaCom will send the SIP INVITE to the configured IP address, UDP port 5060. No SIP REGISTER messages are exchanged. | |
| − | + | ==== Registrar trunk node ==== | |
| + | Alternatively, a SIP trunk can be set up as Registrar node. The external SIP device must then send SIP REGISTER to ICX-AlphaCom, to inform ICX-AlphaCom about it Contact address. The contact address may specify an UDP port different from 5060. | ||
| − | + | To use trunked registrar, configure one or more directory numbers of type [[Call remote station feature]] pointing to the Registrar node. The user part of the REGISTER To: URL must match one of the these remote directory numbers. Any number of SIP registrar nodes may be defined. | |
| − | + | Incoming calls are matched to the Registrar node by comparing the INVITE.Via.URL.Host to the last REGISTER.Via.URL.Host. Anyone is allowed to call in via a SIP registrar node, as long as it is routed via the Proxy/gateway that has registered to ICX-AlphaCom. | |
| − | + | Otherwise Registrar trunk node work exactly as a SIP Trunk node with Fixed IP address. | |
| − | |||
| − | |||
| − | |||
| − | + | ===== Pre AMCD 11.2.x.x/SIP 1.29 ===== | |
| − | + | ''One SIP Trunk can also be set up to act as SIP registrar. The external SIP device must then send SIP REGISTER to AlphaCom. AlphaCom stores the IP address and UDP port of the SIP device in a database. When calling from AlphaCom to the trunk, AlphaCom will send the SIP INVITE to the address and port saved from the last REGISTER message.'' | |
| − | + | ''To use trunked registrar, configure one or more directory numbers of type [[Call remote station feature]] pointing to the Registrar node. SIPd will accept registrations from stations with number found in this list of directory numbers. It is the user part of the To: URL that must match one of the remote directory numbers.'' | |
| − | + | ''The SIP registrar node must have the lowest nodenumber of the SIP trunk nodes .'' | |
| − | |||
| − | |||
| − | The | + | ''Incoming calls must have a From:URL.user matching one of the directory numbers associated with the registrar node. Also see [[SIP registrar node - configuration]]. The [[Licenses#SIP_station_license|SIP station license]] controls how many stations are allowed to register to AlphaCom. '' |
| − | ==== Calls from SIP to AlphaCom, trunked mode ==== | + | ==== Calls from SIP to ICX-AlphaCom, trunked mode ==== |
| − | A call from SIP trunk has the following properties in AlphaCom: | + | A call from SIP trunk has the following properties in ICX-AlphaCom: |
* [[Class of service]] = 15 (telephone COS) (since version 01.19, earlier versions used COS 16) | * [[Class of service]] = 15 (telephone COS) (since version 01.19, earlier versions used COS 16) | ||
* [[Call priority]] = 2 (Normal priority) | * [[Call priority]] = 2 (Normal priority) | ||
| Line 69: | Line 81: | ||
* Member of [[UDP group]] 1 and 8 | * Member of [[UDP group]] 1 and 8 | ||
| − | === | + | === SIP as Station === |
| − | ==== | + | In this case the SIP device is considered as a station in ICX-AlphaCom. The operation of a SIP station can be configured in AlphaPro like other intercom stations. Calls to the SIP station behaves much like internal intercom calls. |
| + | |||
| + | Digits dialed in conversation with SIP stations are handled as [[Directory number in conversation]]. Digits dialed in a call with a SIP station, can '''not''' be forwarded to the SIP device. This precludes using "SIP as station" for interfacing to the PSTN. | ||
| + | |||
| + | When a "SIP station" is in call, ICX-AlphaCom consider that station to be ''busy''. ICX-AlphaCom will not allow more than one simultaneous call to a "SIP station". | ||
| + | |||
| + | Devices set up as "SIP station" must send SIP REGISTER messages to ICX-AlphaCom. It is not possible to configure the IP address of the SIP station in ICX-AlphaCom. The user part of the To: URL in the REGISTER message must be the directory number of the station. | ||
| + | |||
| + | The SIP station license controls how many stations are allowed to register to ICX-AlphaCom. There is no license restriction on the number of calls. | ||
| + | |||
| + | For more information, see [[SIP phone as station]]. | ||
| + | |||
| + | == Function == | ||
| + | The following applies to both trunked and station mode. | ||
| + | |||
| + | === Calls === | ||
| + | The SIPd supports 32 simultaneous calls. | ||
| + | |||
| + | The SIPd only supports audio calls. | ||
| + | |||
| + | SIPd supports SIP phones with auto-answer (results in different SIP signaling with no 180 Ringing messages). | ||
| + | |||
| + | |||
| + | ==== 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. 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 ICX-AlphaCom can be configured to only send one codec in its codec list. Then this problem will not occur.}} | ||
| + | |||
| + | ==== Overlapped dialing ==== | ||
| + | In SIP, overlapped dialing means that each digit is forwarded as the user dials it. | ||
| + | |||
| + | SIPd supports overlapped dialing. See [[#Digits in call]] for more details. | ||
| − | The | + | The ICX-AlphaCom can also be configured to handle the collection of all digits dialed from a Zenitel device, 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. See [[SIP trace]] for details. | |
| − | + | ==== Syslog ==== | |
| − | + | All trace events on levels 0 - 2 (ERROR) are also sent to [[Syslog (AlphaCom)|syslog]]. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
== SIP protocol operation == | == 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. | 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. | + | This chapter comments on how ICX-AlphaCom supports SIP, and about limitations. |
First some general comments. | First some general comments. | ||
| Line 100: | Line 139: | ||
SIP URI usage: SIPd assumes the user part of URIs specify a phone/directory number. | 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 does currently not support domain names in SIP URIs (ICX-AlphaCom does not contain a DNS resolver). |
SIPd currently ignores SIP responses not related to INVITE. | SIPd currently ignores SIP responses not related to INVITE. | ||
| Line 122: | Line 161: | ||
The important header fields are To: and Contact: | 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 @) | + | The To: header must match a directory number defined in the ICX-AlphaCom. The user-name part of the SIP URI (before @) must be equal to the directory number in question. Domain (after @) is ignored. |
| − | must be equal to the directory number in question. Domain (after @) is ignored. | ||
| − | The Contact: header gives the | + | The Contact: header gives the address 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. |
| − | 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. Expires=0 also removes the binding. | A * in the Contact list will remove the binding for that user. Expires=0 also removes the binding. | ||
| − | SIPd can only store one contact address for each user. The last Register message overwrites earlier contact addresses | + | SIPd can only store one contact address for each user. The last Register message overwrites earlier contact addresses for that user. |
| − | for that user. | ||
Immediate response will be a ”100 Trying” message. | Immediate response will be a ”100 Trying” message. | ||
| Line 148: | Line 183: | ||
Content-Length: 0 | Content-Length: 0 | ||
</pre> | </pre> | ||
| − | + | Unsuccessful registrations may return | |
* “404 NOT FOUND” if the request was legal, but the number in the To: URI did not match a directory number. | * “404 NOT FOUND” if the request was legal, but the number in the To: URI did not match a directory number. | ||
| Line 183: | Line 218: | ||
</pre> | </pre> | ||
| − | The user part of the "request URI" in the first line (behind INVITE), specifies the directory number of station to be called in AlphaCom (Here: number “104” ). (This was corrected in version 01.24, earlier version used the To: header). | + | The user part of the "request URI" in the first line (behind INVITE), specifies the directory number of station to be called in ICX-AlphaCom (Here: number “104” ). (This was corrected in version 01.24, earlier version used the To: header). |
| − | 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. | + | The information in the From: header is presented on the display of the called station in ICX-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. | 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. | 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 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: | + | The UDP port is the number following “audio” in m=. The RTP payload type is specified in last parameter in m=. ICX-AlphaCom only handles three of the static RTP payloadtypes in RFC 3551: |
* 0: PCMU | * 0: PCMU | ||
| Line 198: | Line 234: | ||
* 9: G722 | * 9: G722 | ||
| − | Dynamic RTP payload types are currently not supported by AlphaCom. a=rtpmap field is therefore not really necessary | + | Dynamic RTP payload types are currently not supported by ICX-AlphaCom. a=rtpmap field is therefore not really necessary for ICX-AlphaCom. |
| − | for AlphaCom. | ||
If the INVITE is valid, SIPd will respond immediately with a 200 OK message, which completes the RTP setup. | 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 | + | The SIP connection is established immediately with a 200 OK, even if connection is not completed to the final destination in ICX-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 ICX-AlphaCom. These are limitations of current version, which may be changed later. |
| − | 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 | + | 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 ICX-AlphaCom end of the RTP connection. |
| − | and port for the AlphaCom end of the RTP connection. | ||
<pre> | <pre> | ||
SIP/2.0 200 OK | SIP/2.0 200 OK | ||
| Line 232: | Line 262: | ||
</pre> | </pre> | ||
| − | === INVITE, outgoing from SIPd / AlphaCom === | + | ==== Matching INVITE to configuration ==== |
| + | To enforce [[Licenses|licensing]] restrictions, an INVITE must be matched to the SIP configuration. It a match is not found, ICX-AlphaCom will reject the call with 403 FORBIDDEN. | ||
| + | |||
| + | * To match a SIP trunk with configured IP address, the '''host''' part of the URL found in the top '''Via:''' header must match the configured IP address. Both IP address and [[AlphaWeb#Hostnames|hostname]] is accepted in the Via header. | ||
| + | * To match SIP trunk registrar node, the '''host''' part of the '''Via:''' URL that must match the '''host''' part of the '''Via:''' URL of the last REGISTER message. | ||
| + | * To match SIP station, the '''user''' part of the '''From:''' URL that must match the station directory number. | ||
| + | |||
| + | Before SIPD version 1.28 ( [[Release Notes AlphaCom 11.0x|Alphasys 11.2.x.x]]) slightly different rules applied: | ||
| + | * SIP trunk with configured IP address used the the host part of the '''From:''' URL. | ||
| + | * Registrar/SIP as station required the station to be <u>REGISTERed</u> to allow the call. From version 1.28 the requirement is relaxed to that the From number must be <u>configured</u>. | ||
| + | |||
| + | === INVITE, outgoing from SIPd / ICX-AlphaCom === | ||
<pre> | <pre> | ||
INVITE sip:52304@169.254.1.101 SIP/2.0 | INVITE sip:52304@169.254.1.101 SIP/2.0 | ||
| Line 263: | Line 304: | ||
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. | 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. | ||
| − | “301 Moved Permanently”, “302 Moved Temporarily” is handled by SIPd (since version 01.24). SIPd will send a new INVITE to the URI specified in the Contact header. (If redirection is to a AlphaCom station, it is handled by SIPd sending the redirected INVITE to self, which result in a second call connected via IP. This should be | + | “301 Moved Permanently”, “302 Moved Temporarily” is handled by SIPd (since version 01.24). SIPd will send a new INVITE to the URI specified in the Contact header. (If redirection is to a ICX-AlphaCom station, it is handled by SIPd sending the redirected INVITE to self, which result in a second call connected via IP. This should be optimized) |
All other status responses >= 300 will terminate the call with a failure tone. | All other status responses >= 300 will terminate the call with a failure tone. | ||
=== Digits in call === | === Digits in call === | ||
| − | + | ICX-AlphaCom supports two methods for sending and receiving digits during a call, RFC4733 (obsoletes RFC2833) and SIP INFO. ICX-AlphaCom will receive digits sent by both methods in a call. But ICX-AlphaCom will send digits in one format only, depending on the SDP negotiation as described below. | |
==== RFC 4733 RTP events ==== | ==== RFC 4733 RTP events ==== | ||
| + | ICX-AlphaCom support [http://tools.ietf.org/html/rfc4733 rfc4733] (Obsoletes: rfc2833). rfc4733/rfc2833 is the widely supported way of transmitting digit events inside a SIP session. This is a way of embedding DTMF events within the RTP media stream. | ||
| − | + | There is no configuration in ICX-AlphaCom for this. ICX-AlphaCom will always offer rfc4733 events. If accepted, ICX-AlphaCom will send digits as rfc4733 events. Otherwise ICX-AlphaCom will send the events as SIP INFO. | |
| − | |||
| − | There is no configuration in AlphaCom for this. AlphaCom will always offer rfc4733 events. If accepted, AlphaCom will send digits as rfc4733 events. Otherwise AlphaCom will send the events as SIP INFO. | ||
The SDP media description typically looks like | The SDP media description typically looks like | ||
| Line 282: | Line 322: | ||
a=rtpmap:'''103''' telephone-event/8000 | a=rtpmap:'''103''' telephone-event/8000 | ||
| − | ... where 103 is the RTP payload number. For out going INVITE, AlphaCom will use payload type 103. For | + | ... where 103 is the RTP payload number. For out going INVITE, ICX-AlphaCom will use payload type 103. For incoming call, ICX-AlphaCom uses the payloadtype from the incoming INVITE. The outgoing payload number can be changed by setting the NVRAM variable .ex_profile.glob_const.rtp_event_pt from [[TST console]]. |
| − | AlphaCom isolates the rfc4733 RTP digits to the leg between the SIP-AlphaCom and the outside SIP device. AlphaCom extracts RTP digit events from SIP in the first AlphaCom, before forwarding the audio to other AlphaComs and/or IP stations. The extracted digits are handled out of band according to normal AlphaCom procedures. Digits | + | ICX-AlphaCom isolates the rfc4733 RTP digits to the leg between the SIP-AlphaCom and the outside SIP device. ICX-AlphaCom extracts RTP digit events from SIP in the first ICX-AlphaCom, before forwarding the audio to other ICX-AlphaComs and/or IP stations. The extracted digits are handled out of band according to normal ICX-AlphaCom procedures. Digits dialed on the ICX-AlphaCom are injected into the RTP stream at the same ICX-AlphaCom closest to the SIP link. |
| − | RFC 4733 support was | + | RFC 4733 support was released in 10.60.0.0. |
==== INFO ==== | ==== INFO ==== | ||
| − | SIP INFO messages can be used to send and receive single digits | + | SIP INFO messages can be used to send and receive single digits dialed 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 | + | ICX-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 dialed 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 | + | ICX-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 dialing from an internal ICX-AlphaCom station. * is handled as M-press, and # as M-release. |
Example of an outgoing INFO digit message: | Example of an outgoing INFO digit message: | ||
| Line 315: | Line 355: | ||
The format expected in incoming INFO messages is similar. | 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 | + | “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 version 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). |
| − | encoded as a single letter 0 – 9. * and # are encoded as the letters * and # (from | ||
| − | 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. | Duration is hardcoded to 250 (ms) in outgoing messages, and is ignored for incoming messages. | ||
| Line 326: | Line 364: | ||
* 400 BAD_REQUEST : Incoming INVITE: Missing To or From URLs, or missing m= lines in SDP part | * 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 | * 403 FORBIDDEN : Incoming INVITE: Validation of From: SIP header failed. Invite is accepted if | ||
| − | ** user part of from-URL matches a | + | ** user part of from-URL matches a registered user, or |
| − | ** IP address of from-URL matches a | + | ** IP address of from-URL matches a configured "SIP trunk". |
*503 SERVICE_UNAVAILABLE : Failed to allocate internal data structure | *503 SERVICE_UNAVAILABLE : Failed to allocate internal data structure | ||
| Line 342: | Line 380: | ||
* codec negotiation rfc3264 not handled | * codec negotiation rfc3264 not handled | ||
| − | [[Category:AlphaCom | + | == SIPD implementation notes == |
| − | [[Category:SIP]] | + | AMCD extracts the configuration relevant to SIPd and puts it in a text file, /tmp/sipd_config.json. SIPd reads this file at start up, and when the file changes. |
| + | |||
| + | SIPD stores registered SIP stations in a SqLite database in /var/opt/amc/nvram/sipd.sqlite. To see contents: | ||
| + | |||
| + | sqlite3 -header -column /var/opt/amc/nvram/sipd.sqlite "select * from RegUsers" | ||
| + | |||
| + | SIPD connects to AMCD on TCP port 40000 | ||
| + | |||
| + | [[Category: ICX-AlphaCom - SIP Integration]] | ||
| + | [[Category: AlphaCom - SIP Integration]] | ||
Latest revision as of 13:45, 23 February 2023
Contents
SIPd Overview
The SIPd is a signaling gateway. It handles call setup and termination requests and does the necessary conversions between the AlphaNet and SIP protocols.
The SIPd is an internal process running in the ICX-500 or the AMC-IP board (AlphaCom). It is connected to the ICX-AlphaCom or AlphaCom running on the same device. All requests from Zenitel devices are received via the ICX-AlphaCom node. The RTP media flows directly between the RtpDaemon and the SIP phones, without any involvement from SIPd.
SIP interfacing in ICX-AlphaCom is configured in AlphaPro.
A SIP device can be used with ICX-AlphaCom in one of two different modes:
- SIP trunk
- SIP as station
Both modes can be used in ICX-AlphaCom simultaneously, but a given SIP device can only be configured for use in one mode in ICX-AlphaCom
Operating modes
SIP Trunk
Trunked mode is intended for connection to an external system with many telephones, it may be a SIP proxy, a SIP PBX or a PSTN gateway to mention a few. Use this mode if ICX-AlphaCom only should know about the SIP proxy/PBX/gateway, not about the individual telephones. It is technically possible to connect a single SIP phone as a trunk, but it is usually better to connect single telephones as "SIP station", see below.
ICX-AlphaCom allow multiple conversations to a SIP trunk. The number of simultaneous conversations are limited by:
- the license: Licenses for ICX-500 and ICX-AlphaCom Core or SIP trunk license in AlphaCom
- the availability of VoIP channels or the optional configuration of maximum number of lines used for each trunk
The "ICX-AlphaCom" restriction for number of lines for each trunk is configurable from AlphaPro and from the Billing web trunk menu. (or TST->nvram)
If maximum number of simultaneous conversations is reached (max lines configured for each trunk or available licenses):
- Calling attempt by users with high setup priority will break down an existing call with lower priority to free a trunk link.
- Calling attempt by users with same or lower setup priority will start camping for a free link, Camp tone and "Busy" in the display.
In a system where the number of simultaneous lines supported in the external system is less that the ICX-AlphaCom restrictions, when calling from ICX-AlphaCom to SIP trunk, you only get busy tone if the SIP equipment responded with a busy SIP response code (486, 600).
When calling from an ICX-AlphaCom station to a SIP trunk, the user will usually dial additional digits to address the actual telephone. This may be done in two different ways:
- The access number to the trunk is configured so that ICX-AlphaCom (AMCD) will collect a number of digits, before sending a INVITE with the complete number.
- The access number to the trunk is configured so that ICX-AlphaCom immediately connects to the proxy/PBX/gateway, and subsequent digits are forwarded as #Digits in call.
ICX-AlphaCom will accept incoming call from anywhere (no restriction on SIP.From:), as long as the last hop of the call is via the proxy/PBX/gateway configured for the trunk.
A SIP Trunk is configured as a virtual AlphaNet Node with the "exchange_class" set to SIP.
To configure access numbers to the trunk for outward dialing, use Call remote exchange feature or Call remote station feature. It the access number itself should be included in the outgoing INVITE, use the latter. Either way use "param2" if ICX-AlphaCom should collect more digits before sending INVITE.
The SIP routing of SIP trunk node can be configured in two different ways:
- Configured IP address
- Registrar mode
Fixed IP address
In this case the IP address of the SIP device is configured in AlphaPro. It is only possible to configure one single address. It is possible to enter a hostname, if the IP address of the hostname is configured in AlphaWeb#Hostnames.
UDP Port
It is possible to configure the UDP port from default SIP UDP port 5060. Thus must be done in the nvram:
.ex_profile.ip_config.sip_data = 5060
|
This is best done using an event:
The port in the firewall must also be changed.
When calling from ICX-AlphaCom to the trunk, ICX-AlphaCom will send the SIP INVITE to the configured IP address, UDP port 5060. No SIP REGISTER messages are exchanged.
Registrar trunk node
Alternatively, a SIP trunk can be set up as Registrar node. The external SIP device must then send SIP REGISTER to ICX-AlphaCom, to inform ICX-AlphaCom about it Contact address. The contact address may specify an UDP port different from 5060.
To use trunked registrar, configure one or more directory numbers of type Call remote station feature pointing to the Registrar node. The user part of the REGISTER To: URL must match one of the these remote directory numbers. Any number of SIP registrar nodes may be defined.
Incoming calls are matched to the Registrar node by comparing the INVITE.Via.URL.Host to the last REGISTER.Via.URL.Host. Anyone is allowed to call in via a SIP registrar node, as long as it is routed via the Proxy/gateway that has registered to ICX-AlphaCom.
Otherwise Registrar trunk node work exactly as a SIP Trunk node with Fixed IP address.
Pre AMCD 11.2.x.x/SIP 1.29
One SIP Trunk can also be set up to act as SIP registrar. The external SIP device must then send SIP REGISTER to AlphaCom. AlphaCom stores the IP address and UDP port of the SIP device in a database. When calling from AlphaCom to the trunk, AlphaCom will send the SIP INVITE to the address and port saved from the last REGISTER message.
To use trunked registrar, configure one or more directory numbers of type Call remote station feature pointing to the Registrar node. SIPd will accept registrations from stations with number found in this list of directory numbers. It is the user part of the To: URL that must match one of the remote directory numbers.
The SIP registrar node must have the lowest nodenumber of the SIP trunk nodes .
Incoming calls must have a From:URL.user matching one of the directory numbers associated with the registrar node. Also see SIP registrar node - configuration. The SIP station license controls how many stations are allowed to register to AlphaCom.
Calls from SIP to ICX-AlphaCom, trunked mode
A call from SIP trunk has the following properties in ICX-AlphaCom:
- Class of service = 15 (telephone COS) (since version 01.19, earlier versions used COS 16)
- Call priority = 2 (Normal priority)
- Group Access Level = 2
- Member of UDP group 1 and 8
SIP as Station
In this case the SIP device is considered as a station in ICX-AlphaCom. The operation of a SIP station can be configured in AlphaPro like other intercom stations. Calls to the SIP station behaves much like internal intercom calls.
Digits dialed in conversation with SIP stations are handled as Directory number in conversation. Digits dialed in a call with a SIP station, can not be forwarded to the SIP device. This precludes using "SIP as station" for interfacing to the PSTN.
When a "SIP station" is in call, ICX-AlphaCom consider that station to be busy. ICX-AlphaCom will not allow more than one simultaneous call to a "SIP station".
Devices set up as "SIP station" must send SIP REGISTER messages to ICX-AlphaCom. It is not possible to configure the IP address of the SIP station in ICX-AlphaCom. The user part of the To: URL in the REGISTER message must be the directory number of the station.
The SIP station license controls how many stations are allowed to register to ICX-AlphaCom. There is no license restriction on the number of calls.
For more information, see SIP phone as station.
Function
The following applies to both trunked and station mode.
Calls
The SIPd supports 32 simultaneous calls.
The SIPd only supports audio calls.
SIPd supports SIP phones with auto-answer (results in different SIP signaling with no 180 Ringing messages).
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. 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.
|
SIP phones that do not use the first matching codec from the codec lists are not supported by SIPd. The ICX-AlphaCom can be configured to only send one codec in its codec list. Then this problem will not occur. |
Overlapped dialing
In SIP, overlapped dialing means that each digit is forwarded as the user dials it.
SIPd supports overlapped dialing. See #Digits in call for more details.
The ICX-AlphaCom can also be configured to handle the collection of all digits dialed from a Zenitel device, 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. See SIP trace for details.
Syslog
All trace events on levels 0 - 2 (ERROR) are also sent to syslog.
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 ICX-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 (ICX-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.
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
The important header fields are To: and Contact:
The To: header must match a directory number defined in the ICX-AlphaCom. The user-name part of the SIP URI (before @) must be equal to the directory number in question. Domain (after @) is ignored.
The Contact: header gives the address 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. Expires=0 also removes the binding.
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”
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
Unsuccessful 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
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
The user part of the "request URI" in the first line (behind INVITE), specifies the directory number of station to be called in ICX-AlphaCom (Here: number “104” ). (This was corrected in version 01.24, earlier version used the To: header).
The information in the From: header is presented on the display of the called station in ICX-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=. ICX-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 ICX-AlphaCom. a=rtpmap field is therefore not really necessary for ICX-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 ICX-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 ICX-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 ICX-AlphaCom end of the RTP connection.
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
Matching INVITE to configuration
To enforce licensing restrictions, an INVITE must be matched to the SIP configuration. It a match is not found, ICX-AlphaCom will reject the call with 403 FORBIDDEN.
- To match a SIP trunk with configured IP address, the host part of the URL found in the top Via: header must match the configured IP address. Both IP address and hostname is accepted in the Via header.
- To match SIP trunk registrar node, the host part of the Via: URL that must match the host part of the Via: URL of the last REGISTER message.
- To match SIP station, the user part of the From: URL that must match the station directory number.
Before SIPD version 1.28 ( Alphasys 11.2.x.x) slightly different rules applied:
- SIP trunk with configured IP address used the the host part of the From: URL.
- Registrar/SIP as station required the station to be REGISTERed to allow the call. From version 1.28 the requirement is relaxed to that the From number must be configured.
INVITE, outgoing from SIPd / ICX-AlphaCom
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
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.
“301 Moved Permanently”, “302 Moved Temporarily” is handled by SIPd (since version 01.24). SIPd will send a new INVITE to the URI specified in the Contact header. (If redirection is to a ICX-AlphaCom station, it is handled by SIPd sending the redirected INVITE to self, which result in a second call connected via IP. This should be optimized)
All other status responses >= 300 will terminate the call with a failure tone.
Digits in call
ICX-AlphaCom supports two methods for sending and receiving digits during a call, RFC4733 (obsoletes RFC2833) and SIP INFO. ICX-AlphaCom will receive digits sent by both methods in a call. But ICX-AlphaCom will send digits in one format only, depending on the SDP negotiation as described below.
RFC 4733 RTP events
ICX-AlphaCom support rfc4733 (Obsoletes: rfc2833). rfc4733/rfc2833 is the widely supported way of transmitting digit events inside a SIP session. This is a way of embedding DTMF events within the RTP media stream.
There is no configuration in ICX-AlphaCom for this. ICX-AlphaCom will always offer rfc4733 events. If accepted, ICX-AlphaCom will send digits as rfc4733 events. Otherwise ICX-AlphaCom will send the events as SIP INFO.
The SDP media description typically looks like
m=audio 2308 RTP/AVP 0 8 103 a=fmtp:103 0-15 a=rtpmap:103 telephone-event/8000
... where 103 is the RTP payload number. For out going INVITE, ICX-AlphaCom will use payload type 103. For incoming call, ICX-AlphaCom uses the payloadtype from the incoming INVITE. The outgoing payload number can be changed by setting the NVRAM variable .ex_profile.glob_const.rtp_event_pt from TST console.
ICX-AlphaCom isolates the rfc4733 RTP digits to the leg between the SIP-AlphaCom and the outside SIP device. ICX-AlphaCom extracts RTP digit events from SIP in the first ICX-AlphaCom, before forwarding the audio to other ICX-AlphaComs and/or IP stations. The extracted digits are handled out of band according to normal ICX-AlphaCom procedures. Digits dialed on the ICX-AlphaCom are injected into the RTP stream at the same ICX-AlphaCom closest to the SIP link.
RFC 4733 support was released in 10.60.0.0.
INFO
SIP INFO messages can be used to send and receive single digits dialed during a call.
ICX-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 dialed by DAK keys 2 to 5.
ICX-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 dialing from an internal ICX-AlphaCom station. * is handled as M-press, and # as M-release.
Example of an outgoing INFO digit message:
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
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 version 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 registered user, or
- IP address of from-URL matches a configured "SIP trunk".
- 503 SERVICE_UNAVAILABLE : Failed to allocate internal data structure
Limitations
Very very incomplete ...
- Early media not supported (SDP in 1xx responses)
- Late SDP offer not supported (INVITE with no SDP)
- SIP authentication not supported
- SIPS not supported
- codec negotiation rfc3264 not handled
SIPD implementation notes
AMCD extracts the configuration relevant to SIPd and puts it in a text file, /tmp/sipd_config.json. SIPd reads this file at start up, and when the file changes.
SIPD stores registered SIP stations in a SqLite database in /var/opt/amc/nvram/sipd.sqlite. To see contents:
sqlite3 -header -column /var/opt/amc/nvram/sipd.sqlite "select * from RegUsers"
SIPD connects to AMCD on TCP port 40000