<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/en/2171/18/9/_/styles/combined.css?spaceKey=TOP&forWysiwyg=true" type="text/css">
</head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
<h2><a href="https://wiki.asterisk.org/wiki/display/TOP/Hello+World+-+Asterisk+SCF+Style">Hello World - Asterisk SCF Style</a></h2>
<h4>Page <b>edited</b> by <a href="https://wiki.asterisk.org/wiki/display/~beagles">Brent Eagles</a>
</h4>
<br/>
<h4>Changes (31)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >We will use the bare essentials for this. This will require the use of the following components: <br> <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">|| Component name || Source code repository || Description || <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">* ServiceDisovery:</span> <span class="diff-added-words"style="background-color: #dfd;">| Service Locator | servicediscovery |</span> The other components use this to advertise themselves and to find components they rely upon to operate. <span class="diff-added-words"style="background-color: #dfd;">|</span> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">* SIP: This handles SIP signaling. This is also where we configure SIP endpoints. <br>* Media-RTP-PJMEDIA: This handles the RTP setup and media streams. <br>* BasicRouting: This will do endpoint lookup and bridge setup. <br>* Bridging: This will connect the sessions and their associated media. <br>* MediaFormatGeneric: This contains descriptor information for the media type we will use in our call. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">| SIP Session Gateway | sip | Handles SIP signaling. This is also where we configure SIP endpoints | <br>| RTP Media Gateway | media_rtp_pjmedia | Handles RTP setup and media streams | <br>| Basic Routing | routing | Endpoint lookup, call routing and bridging | <br>| Bridge Manager | bridging | Connects Asterisk SCF and mediates signalling and under some circumstances media interconnection | <br>| Generic Media Format | mediaformatgeneric | Hosts media format descriptor information | <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-changed-lines" >We will run the above components in separate icebox instances. It would be possible to run them in a single icebox instance, but doing it this way allows for the individual components' configurations to be changed more easily. <span class="diff-added-words"style="background-color: #dfd;">(TODO: why is that exactly? -beagles)</span> <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">After the components are running, we will need to push additional configuration to the SIP component in order for SIP services to be started and in order for endpoints to be created. This will be done using the provided {{SipConfigurator.py}} script in the SIP repo's {{/config}} directory. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">The SIP Session Gateway and RTP Media Gateway require configuration. Once the components are all up and running we need to run component's respective [configurator script|Component Configuration] to configure relevant endpoints, transports, etc.. The configurator scripts are found in each component's source code repository in the config directory (e.g. sip/config/SIPConfigurator.py). <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">The following examples will be written with the assumptions that the gitall script is in the {{/home/asteriskscf}}. For example, the SIP repo will be in {{/home/asteriskscf/gitall/sip}}. If you are using a different path for your repos, then make the appropriate changes to the instructions below. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{note} <br>The Generic Media Format component can also be configured if you are [adding a new media format]. Since the [built in supported media formats] are probably sufficient, we will skip that for now. <br>{note} <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h1. Getting the components configured <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">The following examples are written with the assumption that you have a cloned the gitall repository into the {{/home/asteriskscf}} directory. For example, the SIP repository will be in {{/home/asteriskscf/gitall/sip}}. If gitall is in a different directory, then make the appropriate changes to the instructions below. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Each component will require an icebox configuration file to give it essential information like where to find the ServiceLocator, what host and port its services should run on, and various other component-specific options. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">h1. Starting the Asterisk SCF Components <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">For your convenience, [this page|Example IceBox Config Files] has all the icebox configuration files you will need in order to start your components. [This page|Notes on Ice Config Files] has a bit of an explanation behind a few of the configuration options. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">The Asterisk SCF components are IceBox services so each component will require an [icebox configuration|Common Component Icebox Configuration] file to give it essential startup information such as the service entry point, the Service Locator proxy, what host/IP addresses and ports should be used and other component-specific options. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h1. Starting Asterisk SCF <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">For your convenience, [example icebox configuration files| Example IceBox Config Files] are available that should work to get your components up and running. See the [Common Component Icebox Configuration] page for more information on the contents of these files. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Now that you have configuration files written, you'll need to start each of the components. <br>To start a component, you'll need to issue the following command: <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">Once you have the IceBox configuration files, you can to start the components. Each component can be started by running IceBox with the path to the appropriate IceBox configuration file. The commands will have the general form of: <br></td></tr>
<tr><td class="diff-unchanged" > <br>{noformat} <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >{noformat} <br> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">For instance, if you have called your routing configuration file {{routing.icebox}}, and it is saved in the routing repo's config directory, then you would start the routing service using the command <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{note} <br>If you built a debug version on Windows (which you most likely did), you need to run iceboxd.exe not icebox.exe so that IceBox and your component both use the debug version of the Microsoft runtime libraries. <br>{note} <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">For instance, if you have named the routing configuration file {{routing.icebox}} and saved it in the routing repository's config directory, then you would start the routing service using the command <br> <br></td></tr>
<tr><td class="diff-unchanged" >{noformat} <br>$ icebox --Ice.Config=/home/asteriskscf/gitall/routing/config/routing.icebox <br>{noformat} <br> <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">You will need to issue {{icebox}} commands for each of the components. It would probably do you well to create a small script to start up all the services. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">{tip} <br>It may be a good idea to start the components in a terminal window (console window on Windows) so you can see all of the output of the command. Unless you have set things up so all of the shared libraries, etc. are in default paths you are most likely doing this anyways. <br>{tip} <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h1. Configuring SIP endpoints. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">Since the example IceBox configuration files only load a single component, you need to run an {{icebox}} command for each one. A simple startup script is a good idea but left as an exercise for the reader (that is *you*!). <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">At this point you should have all of your components up and running. Unfortunately, they cannot really do much of anything without further application-specific configuration. In this case, we need to configure the SIP component so that it will be able to handle calls. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">h1. Configuring the Components <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">To do this, we will made use of the {{SipConfigurator.py}} script in the {{config}} directory of the {{sip}} repo. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">Once all of the components are up and running you are ready to configure them. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">In this case, we need to configure the SIP component so that it will be able to handle calls. <br> <br>h2. Configuring the Generic Media Format Component <br> <br>You do not *really* have to do this, but it is good practice. Besides <br> <br> <br>To do this, we will made use of the {{SIPConfigurator.py}} script in the {{config}} directory of the {{sip}} repository. <br> <br></td></tr>
<tr><td class="diff-unchanged" >h3. Creating a configuration file <br> <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<p>You've managed to get Asterisk SCF completely downloaded and compiled, so now what? In this tutorial, I will give a step-by-step set of instructions for getting two SIP phones to communicate with each other. We will be foregoing features such as registration and authentication for the sake of simplicity.</p>
<h1><a name="HelloWorld-AsteriskSCFStyle-AnOverview"></a>An Overview</h1>
<p>We will use the bare essentials for this. This will require the use of the following components:</p>
<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Component name </th>
<th class='confluenceTh'> Source code repository </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> Service Locator </td>
<td class='confluenceTd'> servicediscovery </td>
<td class='confluenceTd'> The other components use this to advertise themselves and to find components they rely upon to operate. </td>
</tr>
<tr>
<td class='confluenceTd'> SIP Session Gateway </td>
<td class='confluenceTd'> sip </td>
<td class='confluenceTd'> Handles SIP signaling. This is also where we configure SIP endpoints </td>
</tr>
<tr>
<td class='confluenceTd'> RTP Media Gateway </td>
<td class='confluenceTd'> media_rtp_pjmedia </td>
<td class='confluenceTd'> Handles RTP setup and media streams </td>
</tr>
<tr>
<td class='confluenceTd'> Basic Routing </td>
<td class='confluenceTd'> routing </td>
<td class='confluenceTd'> Endpoint lookup, call routing and bridging </td>
</tr>
<tr>
<td class='confluenceTd'> Bridge Manager </td>
<td class='confluenceTd'> bridging </td>
<td class='confluenceTd'> Connects Asterisk SCF and mediates signalling and under some circumstances media interconnection </td>
</tr>
<tr>
<td class='confluenceTd'> Generic Media Format </td>
<td class='confluenceTd'> mediaformatgeneric </td>
<td class='confluenceTd'> Hosts media format descriptor information </td>
</tr>
</tbody></table>
</div>
<p>We will run the above components in separate icebox instances. It would be possible to run them in a single icebox instance, but doing it this way allows for the individual components' configurations to be changed more easily. (TODO: why is that exactly? -beagles)</p>
<p>The SIP Session Gateway and RTP Media Gateway require configuration. Once the components are all up and running we need to run component's respective <a href="/wiki/display/TOP/Component+Configuration" title="Component Configuration">configurator script</a> to configure relevant endpoints, transports, etc.. The configurator scripts are found in each component's source code repository in the config directory (e.g. sip/config/SIPConfigurator.py).</p>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>The Generic Media Format component can also be configured if you are <a href="/wiki/display/TOP/Adding+a+new+media+format" title="Adding a new media format">Adding a new media format</a>. Since the <a href="/wiki/pages/createpage.action?spaceKey=TOP&title=built+in+supported+media+formats&linkCreation=true&fromPageId=19007195" class="createlink">built in supported media formats</a> are probably sufficient, we will skip that for now.</td></tr></table></div>
<p>The following examples are written with the assumption that you have a cloned the gitall repository into the <tt>/home/asteriskscf</tt> directory. For example, the SIP repository will be in <tt>/home/asteriskscf/gitall/sip</tt>. If gitall is in a different directory, then make the appropriate changes to the instructions below.</p>
<h1><a name="HelloWorld-AsteriskSCFStyle-StartingtheAsteriskSCFComponents"></a>Starting the Asterisk SCF Components</h1>
<p>The Asterisk SCF components are IceBox services so each component will require an <a href="/wiki/display/TOP/Common+Component+Icebox+Configuration" title="Common Component Icebox Configuration">icebox configuration</a> file to give it essential startup information such as the service entry point, the Service Locator proxy, what host/IP addresses and ports should be used and other component-specific options.</p>
<p>For your convenience, <a href="/wiki/display/TOP/Example+IceBox+Config+Files" title="Example IceBox Config Files">example icebox configuration files</a> are available that should work to get your components up and running. See the <a href="/wiki/display/TOP/Common+Component+Icebox+Configuration" title="Common Component Icebox Configuration">Common Component Icebox Configuration</a> page for more information on the contents of these files.</p>
<p>Once you have the IceBox configuration files, you can to start the components. Each component can be started by running IceBox with the path to the appropriate IceBox configuration file. The commands will have the general form of:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>$ icebox --Ice.Config=path/to/component/config/file
</pre>
</div></div>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>If you built a debug version on Windows (which you most likely did), you need to run iceboxd.exe not icebox.exe so that IceBox and your component both use the debug version of the Microsoft runtime libraries.</td></tr></table></div>
<p>For instance, if you have named the routing configuration file <tt>routing.icebox</tt> and saved it in the routing repository's config directory, then you would start the routing service using the command</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>$ icebox --Ice.Config=/home/asteriskscf/gitall/routing/config/routing.icebox
</pre>
</div></div>
<div class='panelMacro'><table class='tipMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/check.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>It may be a good idea to start the components in a terminal window (console window on Windows) so you can see all of the output of the command. Unless you have set things up so all of the shared libraries, etc. are in default paths you are most likely doing this anyways.</td></tr></table></div>
<p>Since the example IceBox configuration files only load a single component, you need to run an <tt>icebox</tt> command for each one. A simple startup script is a good idea but left as an exercise for the reader (that is <b>you</b>!).</p>
<h1><a name="HelloWorld-AsteriskSCFStyle-ConfiguringtheComponents"></a>Configuring the Components</h1>
<p>Once all of the components are up and running you are ready to configure them. </p>
<p>In this case, we need to configure the SIP component so that it will be able to handle calls.</p>
<h2><a name="HelloWorld-AsteriskSCFStyle-ConfiguringtheGenericMediaFormatComponent"></a>Configuring the Generic Media Format Component</h2>
<p>You do not <b>really</b> have to do this, but it is good practice. Besides </p>
<p>To do this, we will made use of the <tt>SIPConfigurator.py</tt> script in the <tt>config</tt> directory of the <tt>sip</tt> repository.</p>
<h3><a name="HelloWorld-AsteriskSCFStyle-Creatingaconfigurationfile"></a>Creating a configuration file</h3>
<p>The configurator reads in a .ini-style file with configuration options specified. Below is an example configuration file to use.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>
# First, we need to configure a transport for the SIP component to use.
# Feel free to give it whatever name you want.
[udp-transport]
# This tells the configurator what type of configuration
# section this is. In this case, we're configuring a
# UDP transport
type=transport-udp
# This tells the IP address and port to bind to for this transport.
# This can be an IPv4 or IPv6 address.
host=0.0.0.0
port=5060
# Now we need to configure endpoints. Endpoints each comprise their
# own section.
[1000]
# This tells the configurator that this section describes
# an endpoint
type=endpoint
# The IP address or hostname and port of the endpoint.
targethost=<IP address or hostname of endpoint 1000>
targetport=5060
# The IP address and port that we tell the endpoint to
# send their SIP signaling to when we call it.
sourcehost=<IP address of the Asterisk SCF server>
sourceport=5060
# This specifies the allowable direction(s) for communications
# between Asterisk SCF and the endpoint. Setting this to "both"
# allows for both incoming and outgoing calls to be made with
# this endpoint.
direction=both
# This specifies what formats to offer in SDP offers and what
# formats to accept in an SDP answer. For our example, we will
# use 8000 Hz G.711 uLAW audio.
formats=ulaw/8000
# This endpoint will mostly be configured the same.
[2000]
type=endpoint
targethost=<IP address or hostname of endpoint 2000>
targetport=5060
sourceport=<IP address of the Asterisk SCF server>
sourceport=5060
direction=both
formats=ulaw/8000
</pre>
</div></div>
<p>We will save this file in the <tt>sip</tt> repo's <tt>config</tt> directory as <tt>Sip.config</tt>. For your convenience, here is the file:</p>
<p><a href="/wiki/download/attachments/19007195/Sip.config?version=2&modificationDate=1323721147826">Sip.config</a></p>
<h3><a name="HelloWorld-AsteriskSCFStyle-Runningtheconfiguratorscript"></a>Running the configurator script</h3>
<p>You'll now need to run the <tt>SipConfigurator.py</tt> script in order to apply the SIP configuration to the running SIP component. The configurator relies on some environment variables to be set, so let's go and do that!</p>
<p>First, you'll need to add a couple of items to your <tt>PYTHONPATH</tt>. You will need to add the path to Ice's python definitions (on Linux, this is /opt/Ice-3.4.2/python/ by default) and the path to the Asterisk SCF <tt>configurator</tt> repo. You will also need to set the <tt>ASTSCF_HOME</tt> environment variable. This is the path to the <tt>slice</tt> subdirectory of the Asterisk SCF <tt>slice</tt> repo. On Unix-like systems, this is done using the following command:</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>$ export PYTHONPATH=/opt/Ice-3.4.2/python:/home/asteriskscf/gitall/configurator
$ export ASTSCF_HOME=/home/asteriskscf/gitall/slice/slice
</pre>
</div></div>
<p>Now that you have the appropriate environment variables set up, you can actually run the python script.</p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>$ cd /home/asteriskscf/gitall/sip/config
$ ./SipConfigurator.py --wipe --config=Sip.config --locator="LocatorService:tcp -p 4411"
</pre>
</div></div>
<p>This should successfully apply your configuration to the running SIP component.</p>
<h3><a name="HelloWorld-AsteriskSCFStyle-Configuringthephones"></a>Configuring the phones</h3>
<p>With this setup, we've named the phones <tt>1000</tt> and <tt>2000</tt>. Asterisk SCF's current endpoint matching scheme is to use the user part in the URI in the From header of an INVITE to determine which endpoint the message is originating from. This means that you will need to configure your phone to identify itself properly. The method will differ per phone. Options such as "Caller ID number" or "Phone Number" are generally good places to set the endpoint name.</p>
<h1><a name="HelloWorld-AsteriskSCFStyle-Placingthecall"></a>Placing the call</h1>
<p>Now you should be able to place calls between the phones. You can dial each phone using the endpoint name for that phone. So for instance, if you wish to call phone <tt>2000</tt> then you can pick up phone <tt>1000</tt> and dial "2000".</p>
<p>With this base configuration in place, you can start to experiment with other configuration options, set up more advanced options like authentication, and maybe achieve inner peace...or inner peaches.</p>
</div>
<div id="commentsSection" class="wiki-content pageSection">
<div style="float: right;" class="grey">
<a href="https://wiki.asterisk.org/wiki/users/removespacenotification.action?spaceKey=TOP">Stop watching space</a>
<span style="padding: 0px 5px;">|</span>
<a href="https://wiki.asterisk.org/wiki/users/editmyemailsettings.action">Change email notification preferences</a>
</div>
<a href="https://wiki.asterisk.org/wiki/display/TOP/Hello+World+-+Asterisk+SCF+Style">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=19007195&revisedVersion=12&originalVersion=11">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/TOP/Hello+World+-+Asterisk+SCF+Style?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>