[Asterisk-doc] docs chapter07.xml,1.3,1.4

[blitzrage]

Comments:
Update of /cvsroot/asterisk/docs
In directory sc8-pr-cvs1:/tmp/cvs-serv12296/docs

Modified Files:
	chapter07.xml 
Log Message:
blitzrage
- added Peter Grace's documentation on Echo Cancellation to chapter 7!

TODO:  Add stuff by Rich Adamson as well for the most complete echo
       cancellation documentation to date! :)
Index: chapter07.xml
===================================================================
RCS file: /cvsroot/asterisk/docs/chapter07.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** chapter07.xml	21 Dec 2003 07:22:07 -0000	1.3
--- chapter07.xml	22 Dec 2003 07:07:31 -0000	1.4
***************
*** 159,163 ****
  	<sect1>
  		<title>Echo Cancellation Issues</title>
! 		<para/>
  	</sect1>
  	<sect1>
--- 159,302 ----
  	<sect1>
  		<title>Echo Cancellation Issues</title>
! 		<sect2>
! 		<title>Introduction</title>
! 		<para>
! 			One of the dirty truths about Asterisk is that if you do not configure your 
! 			Zaptel hardware correctly, you will at one time or another experience 
! 			serious echo issues with connecting VoIP lines to the PSTN.  Thankfully, 
! 			Asterisk has some pretty useful methods for taking care of echo.
! 		</para>
! 
! 		<figure id="echo-fig1"><title>Zaptel Makefile compile options</title>
! 		<programlisting>
! 			#KFLAGS+=-DECHO_CAN_STEVE
! 			#KFLAGS+=-DECHO_CAN_STEVE2
! 			#KFLAGS+=-DECHO_CAN_MARK
! 			KFLAGS+=-DECHO_CAN_MARK2
! 			#KFLAGS+=-DECHO_CAN_MARK3
! 		</programlisting>
! 		</figure>
! 		
! 		<para>
! 			In Figure 7-1, you can see there are several options for echo 
! 			cancellation.  Commenting out all but one of these lines is required.  If 
! 			you'd like to use the MARK3 echo canceller, for instance, you'd comment 
! 			out the MARK2 line and uncomment the MARK3 line.
! 		</para>
! 
! 		<para>
! 			All four of the echo cancellers will do a mediocre to good job of taking 
! 			care of echo, but it takes a little while for Asterisk to properly adjust.  
! 			If you use the MARK2 canceller, there's an additional option:
! 		</para>
! 
! 		<para>
! 		<programlisting>
! 			#KFLAGS+=-DAGGRESSIVE_SUPPRESSOR
! 		</programlisting>
! 		</para>
! 
! 		<para>
! 			That can be added for additional echo cancellation.  Aggressive suppression 
! 			works well, but can make the conversation sound scratchy in the beginning.
! 		</para>
! 		</sect2>
! 
! 		<sect2>
! 		<title>Echo Training</title>
! 			<para>
! 				Now, thanks to the efforts of Brian West and the other Asterisk gang, we 
! 				now have a feature in Zaptel called Echo Training.  Echo training, in my 
! 				experience, works the best out of all of the echo cancellers.
! 			</para>
! 
! 			<figure id="echo-fig2"><title>zapata.conf echo training definition for FXO channel</title>
! 			<programlisting>
! 			[channels]
! 			echocancel=yes
! 			echocancelwhenbridged=yes
! 			echotraining=yes
! 			rxgain=8.2
! 			txgain=1.0
! 			signaling=fxs_ks
! 			channel=1
! 			</programlisting>
! 			</figure>
! 
! 			<para>
! 				Echo training is enabled with two separate sets of settings - first of 
! 				all, make sure you have <option>echocancel=yes</option>, 
! 				<option>echocancelwhenbridged=yes</option>, 
! 				and <option>echotraining=yes</option>.  These are the first steps to 
! 				effective cancellation.  There is another important setup consideration 
! 				that you should follow: properly adjusting your rxgain/txgain.
! 			</para>
! 		</sect2>
! 
! 		<sect2>
! 		<title>Adjusting the rxgain/txgain Settings</title>
! 			<para>
! 				In order to adjust txgain/rxgain properly, you need to use the ztmonitor 
! 				application to check the power of your audio signal as a call is in 
! 				progress.  The steps for tuning rxgain/txgain are as follows:
! 
! 				<orderedlist>
! 				<listitem>
! 					<para>
! 						Set default values of rxgain/txgain to 1.0
! 					</para>
! 				</listitem>
! 				<listitem>
! 					<para>
! 						Initiate a call that flows out of your Zapata device.
! 					</para>
! 				</listitem>
! 				<listitem>
! 					<para>
! 						Look at the ztmonitor visualization (explained below) to see whether the 
! 						audio is in optimal condition.
! 					</para>
! 				</listitem>
! 				<listitem>
! 					<para>
! 						If it is not optimal, increase or decrease the txgain/rxgain levels accordingly.
! 					</para>
! 				</listitem>
! 				</orderedlist>
! 			</para>
! 
! 			<para>
! 				Most people find that they need an rxgain level around 8.0 to have good 
! 				echo cancellation.  The txgain setting varies from installation to 
! 				installation.
! 			</para>
! 
! 			<figure id="echo-fig3"><title>ztmonitor output</title>
! 			<programlisting>
! 				astpbx1:/usr/src/pbx/zaptel# ./ztmonitor 1 -v
! 				Rx############                 Tx#####################
! 			</programlisting>
! 			</figure>
! 
! 			<para>
! 				In the above output, we see a text-based VU meter showing the relative 
! 				power of the audio source.  The Rx channel is right where we want it, 
! 				so the rxgain setting you have in your configuration is good.  The Tx 
! 				level, however, is pegged all the way to the end of the screen (use your 
! 				imagination), in which case the audio is doing something called "over 
! 				deviation" - it's the same thing that happens when people get too close 
! 				to a microphone and the audio is crackly.  When this occurs, the echo 
! 				canceller cannot compensate for the signal as well since it is busy 
! 				receiving artifacts of the audio that "spill" back into the channel.  
! 				In this case, we want to lower the txgain level a bit.
! 			</para>
! 
! 			<para>
! 				Most people who configure echotraining correctly will never hear echo in 
! 				their calls again.  The echo canceller works nearly instantaneously in 
! 				echotraining mode.
! 			</para>
! 		</sect2>
! 
  	</sect1>
  	<sect1>