Author: derek Date: Tue Jul 3 20:17:43 2007 New Revision: 342 Added: sofaswitch/trunk/get_started/answeringmachine.sgml Log: Add this file, which describes the use of the answering machine. Added: sofaswitch/trunk/get_started/answeringmachine.sgml ============================================================================== --- (empty file) +++ sofaswitch/trunk/get_started/answeringmachine.sgml Tue Jul 3 20:17:43 2007 @@ -0,0 +1,165 @@ +<chapter> +<title>Answering machine utility</title> +<titleabbrev>Audio play/record</titleabbrev> + + + +<para> +The sound card (described in previous section) can be utilised in the &sofaswitch; environment, +and it can send/receive audio with any other &sofaswitch; audio +component. The Answering Machine is perhaps the simplest other +audio component, which can play/record audio from/to a wav file. +</para> + +<para> +Build and run the answering machine utility with the commands +<itemizedlist> +<listitem><literal>cd am</literal></listitem> +<listitem><literal>make both</literal></listitem> +<listitem><literal> + ./obj_linux_x86_r/am -s machine_running_server +</literal></listitem> +</itemizedlist> +The options to the answering machine utility specify the name of the machine running the +sofa message server. you will need to adjust the options to correctly specify +the name of the machine running the message server. Thus, if the message server +and the answering machine are on the same computer, you will use the string +<literal>localhost</literal>. +You can see all the available command +options by running the answering machine utility with the command parameter <literal>-h</literal> +</para> + +<para> +For the test script to work, we expect that am is launched from a directory +containing a 16bit, 8khz sound file, called "sample_message.wav" +</para> + +<para> +In the controller directory, there is a python script that will connect the audio +streams from the answering machine and sound executables together. Run this +utility with: +<screen> +python testsound.py machine_running_server +</screen> +Again, you will need to modify this command line to correctly specify the +location of the machine running the server. +</para> + +<para> +The server reports the following messages. +<screen> +controller : am:REQUESTNEWID + am : controller:REQUESTNEWID am1 +controller : am1:transferudp sound + am1 : controller:OutgoingCall am1 + am1 : sound:transferudp sound 10.0.0.5:64000 + sound : am1:transferudp sound 10.0.0.5:61000 done +controller : am1:setannouncementfile sample_message.wav +controller : am1:setreceivedmsgfile derek.wav +controller : am1:hangup + am1 : controller:Terminating +</screen> +The messages are in four groups. +<itemizedlist> +<listitem><para> The controller requests an answering machine entity to send/receive audio from. + The answering machine supervisor sends a message back to the controller, advising + the controller of the new identity. </para></listitem> + +<listitem><para> The controller tells the new identy (<literal>am1</literal>) to connect audio streams with the <literal>sound</literal> + identity. Notice that the controller is not aware of the address used to transfer audio. + </para></listitem> +<listitem><para> The controller tells the answering machine identity to play audio from the file + <literal>sample_message.wav</literal>, and record to the file <literal>derek.wav</literal>.</para></listitem> + +<listitem><para>Advisement notices (call setup, call terminating)</para></listitem> +</itemizedlist> +</para> +<para> +As before, this simple test can be extended by running the <literal>client.py</literal> python script file described above. +You can enquire of the answering machine for status information (command <literal>am:status full</literal>) and you +will see what is available. The answerine machine will reply back +<screen> +am:status full +am:Current Status:----------- +Comms instance count 61 50 11 +Consumer instance count 50 50 0 +pre, active & dead calls 0 1 0 + + Current active nodes: + am51 +</screen> +These figures are designed to provide some diagnostic information about what is going on. +There main purpose is tell you the counts of constructed/allocated class instances, and therefore +provide some guide as to if the system is leaking memory. +</para> + +<para> +There are 11 Comms instances currently availble. One is used in an active call (am51), and the +remaining 10 have connected to the message server. These remaining 10 are therefore ready for +immediate use, should they be requested by the controller. +</para> + +<para> +The Consumer instance count is a class that is very short lived, and designed +to clean up calls after the call has terminated.. In this case, 50 have been +constructed, 50 deleted, and balance is zero. If there are several available +Consumer instances, we have evidence that the calls are not being cleaned up. +Each Consumer instance is a separate thread, created to clean up one call. A +call is cleaned up independently (well, as much as possible) from all other calls. +</para> + +<para> +From running the <literal>client.py</literal> script, while the <literal>testsound.py</literal> script is running, we +can interrogate the message server to see what is happening. We send the command <literal>status full</literal>, +which looks like: +<screen> +status full + Status of the Server +------------------------- +Constructed/Deleted TcpConnections 98 72 26 +Count ready made TcpConnections 10 +Messages Sent Received Dropped Diff 1274 972 108 194 +Current list size 15 + + current nodes + controller + sound + am + am51 + am52 + am53 + am54 + am55 + am56 + am57 + am58 + am59 + am60 + am61 + test +</screen> +</para> + +<para> +The server has reported that there are 26 available <literal>TcpConnection</literal> +class instances. One <literal>TcpConnection</literal> instance is used for each connected +node to the server. The figure of 26 above is correct. +<itemizedlist> +<listitem> 15 are used for the 15 entries in the list</listitem> +<listitem> 10 are stored away, ready for use in connecting nodes</listitem> +<listitem> 1 is on hand, ready to use immediately with the next incoming +connection.</listitem> +</itemizedlist> +</para> + +<para> +The list contains 15 nodes, which is correct. <literal>Controller</literal> is there, who +is running the <literal>testsound.py</literal> script file. Further, <literal>sound</literal> is there, who is +managing the sound card, and is an endpoint for the test. The supervisor +<literal>am</literal> for the answering machine is there. Also, <literal>test</literal> is there, +which is the identity of the node from the <literal>client.py</literal> &python; script. +<literal>am51</literal> is there, who is the current active answering machine node. +Nodes <literal>am52..am61</literal> are the nodes that the answering machine +supervisor has prebuilt, which are ready for use. +</para> +</chapter> \ No newline at end of file