WANPIPE EC API Interface

Author: Alex Feldman

Version 0.3

August 31, 2009

 Contents
WANPIPE EC API global definitions ................................................................................ 3
WANPIPE EC API functions ............................................................................................. 4
wanec_api_config()......................................................................................................... 4
wanec_api_release()........................................................................................................ 4
wanec_api_mode().......................................................................................................... 4
wanec_api_bypass()........................................................................................................ 5
wanec_api_opmode()...................................................................................................... 5
wanec_api_modify() ....................................................................................................... 6
wanec_api_mute()........................................................................................................... 6
wanec_api_dtmf() ........................................................................................................... 7
wanec_api_stats()............................................................................................................ 7
wanec_api_buffer_load() ................................................................................................ 8
wanec_api_buffer_unload() ............................................................................................ 8
wanec_api_playout()....................................................................................................... 9
wanec_api_monitor() ...................................................................................................... 9
Appendix A....................................................................................................................... 11
Appendix B ....................................................................................................................... 12
Revision History ............................................................................................................... 13
WANPIPE EC API global definitions

wan_custom_param_t structure
name Array, char[MAX_PARAM_LEN+1]
Name of custom parameter
sValue Array, char[MAX_VALUE_LEN+1]
Pointer to the buffer that include string value of parameter
dValue u_int32_t
Integer value of custom parameter

wan_custom_conf_t structure
param_no unsigned int
Number of parameters in a list
params wan_custom_param_t*
WANPIPE EC API functions

wanec_api_config()

Load image into EC chip, open and enable all EC channels.

Usage
int wanec_api_config(
char *devname,
int verbose,
wanec_api_config_t *config);
Parameters
devname Sangoma wanpipe device name (like wanpipe1 or wanpipe2).
verbose Verbose mode [0|1|2].
wanec_api_config_t
conf wan_custom_conf_t
List of custom EC chip configuration (see definition below). For
list of custom Echo Cancellation parameters (Appendix B).

wanec_api_release()

Disable and close all EC channels.

Usage
int wanec_api_release(
char *devname,
int verbose,
wanec_api_release_t *release);
Parameters
devname Sangoma wanpipe device name (like wanpipe1 or wanpipe2).
verbose Verbose mode [0|1|2].
wanec_api_release_t
Empty structure.

wanec_api_mode()

Enable/Disable Echo Cancellation all channels from channel map.

Usage
int wanec_api_enable(
char *devname,
 int verbose,
wanec_api_mode_t *mode);
Parameters
devname Sangoma wanpipe device name (like wanpipe1 or wanpipe2).
verbose Verbose mode [0|1|2].
wanec_api_mode_t
enable int
If this value is 1, the function will enable Echo Cancellation for the
cannel. If this value is 0, the function will disable Echo
Cancellation for the channel.
fe_chan_map unsigned long
Bit-map of channels.

wanec_api_bypass()

Enable/Disable internal traffic throught EC chip.

Usage
int wanec_api_bypass(
char* devname,
int verbose);
Parameters
devname Sangoma wanpipe device name (like wanpipe1 or wanpipe2).
verbose Verbose mode [0|1|2].
wanec_api_mode_t
enable int
If this value is 1, the function will enable Bypass mode for the
cannel. If this value is 0, the function will disable Bypass mode for
the channel.
fe_chan_map unsigned long
Bit-map of channels.

wanec_api_opmode()

Modify channel operation mode

Usage
int wanec_api_opmode(
char *devname,
int verbose,
wanec_api_opmode_t *opmode);
Parameters
devname Sangoma wanpipe device name (like wanpipe1 or wanpipe2).
verbose Verbose mode [0|1|2].
wanec_api_opmode_t
 mode int
New Echo Canceller OP MODE for the channels (Appendix A).
fe_chan_map unsigned long
Bit-map of channels.

wanec_api_modify()

Modify channel configuration parameters

Usage
int wanec_api_modify(
char *devname,
int verbose,
wanec_api_modify_t *modify);
Parameters
devname Sangoma wanpipe device name (like wanpipe1 or wanpipe2).
verbose Verbose mode [0|1|2].
wanec_api_modify_t
fe_chan_map unsigned long
Bit-map of channels.
conf wan_custom_conf_t
List of custom EC chip configuration (see definition below). For
list of custom Echo Cancellation parameters (Appendix B).

wanec_api_mute()

Mute/Unmute Echo Canceller channel

Usage
int wanec_api_mute(
char *devname,
int verbose,
wanec_api_mute_t *mute);
Parameters
devname Sangoma wanpipe device name (like wanpipe1 or wanpipe2).
verbose Verbose mode [0|1|2].
wanec_api_mute_t
mode int
Set this value to 1, the function will mute the channel. Set this
value to 2, the function will unmute the channel.
fe_chan_map unsigned long
Bit-map of channels.
port_map unsigned char
Bit-map of port to be mute/unmute. The value can be OR of the
following values: WAN_EC_CHANNEL_PORT_SIN
 WAN_EC_CHANNEL_PORT_SOUT
WAN_EC_CHANNEL_PORT_RIN
WAN_EC_CHANNEL_PORT_ROUT.

wanec_api_dtmf()

Enable/Disable DTMF detection of channels from channel map.

Usage
int wanec_api_dtmf(
char *devname,
int verbose,
wanec_api_dtmf_t *dtmf)
Parameters
devname Sangoma wanpipe device name (like wanpipe1 or wanpipe2).
verbose Verbose mode [0|1|2].
wanec_api_dtmf_t
enable int
Set this value to 1, the function will enable dtmf detection on this
channel. Set this value to 0, the function will disable dtmf detection
on this channel.
fe_chan_map unsigned long
Bit-map of channels.
port_map unsigned char
Bit-map of port. The value can be OR of the following values:
WAN_EC_CHANNEL_PORT_SOUT - SOUT port on EC chip
WAN_EC_CHANNEL_PORT_ROUT - ROUT port on EC chip
type_map unsigned char
Bit-map of event types to be enabled/disabled for detection. The
value can be OR of the following values:
WAN_EC_TONE_PRESENT - Event present
WAN_EC_TONE_STOP - Event stop

wanec_api_stats()

Reading Chip/Channel statistics from EC chip.

Usage
int wanec_api_stats(
char *devname,
int verbose,
wanec_api_stats_t *stats);
Parameters
devname Sangoma wanpipe device name (like wanpipe1 or wanpipe2).
verbose Verbose mode [0|1|2].
wanec_api_stats_t
 full int
Set this value to 1 in order to print full Chip/Channel statistics.
Otherwise, the function will print only main statistics for EC
Chip/Channel.
fe_chan int
If this value is 0, the function will read EC chip statistics.
Otherwise, the function will read statistics for specified channel
reset int
Reset statistics counters (not used).
silent int
Do not print statistics (not used).

wanec_api_buffer_load()

Load buffer to EC chip.

Usage
int wanec_api_buffer_load(
char *devname,
int verbose,
wanec_api_bufferload_t *bufferload);
Parameters
devname Sangoma wanpipe device name (like wanpipe1 or wanpipe2).
verbose Verbose mode [0|1|2].
wanec_api_bufferload_t
buffer char*
Pointer to the valid buffer to be loaded into Echo Canceller
external memory.
buffer_id unsigned int
This value will return the buffer index of loaded buffer in the Echo
Canceller buffer memory. This value will be used to play the
buffer and unload the tone from external EC memory.

wanec_api_buffer_unload()

Unload buffer from EC chip.

Usage
int wanec_api_buffer_unload(
char *devname,
int verbose,
wanec_api_bufferunload_t *bufferunload);
Parameters
devname Sangoma wanpipe device name (like wanpipe1 or wanpipe2).
verbose Verbose mode [0|1|2].
wanec_api_bufferunload_t
 buffer_id unsigned int
Buffer index return by wanec_api_buffer_load.

wanec_api_playout()

Start/Stop playout buffer on specific channel.

Usage
int wanec_api_playout(
char *devname,
int verbose,
wanec_api_playout_t *playout);
Parameters
devname Sangoma wanpipe device name (like wanpipe1 or wanpipe2).
verbose Verbose mode [0|1|2].
wanec_api_playout_t
start int
Set this value to 1 in order to start play the tone. Set this value to 0
in order to stop play the buffer.
buffer_id unsigned int
Buffer index returned by wanec_api_buffer_load function.
fe_chan int
Channel number
port unsigned char
This is the channel port on which the buffer will be played
(WAN_EC_CHANNEL_PORT_SOUT or
WAN_EC_CHANNEL_PORT_ROUT).
duration int
This parameter represents the time (duration), in milliseconds, that
this buffer should be played.
notifyonstop int
Enable generation of playout event on stop.

wanec_api_monitor()

Start/Stop monitoring the selected channel by EC chip. This function should be called
twice. First time, the function should be called with specific channel to be monitored.
Second time, the function should called with channel parameter set to 0 in order to
retrieve the monitored data and at least 2 minutes after first call in order to have
enough data. The name of generated file is
wan_ec_<wanpipe_device>_chan<fe_chan>_<date>_<time>.bin.
Usage
int wanec_api_monitor(
char *devname,
int verbose,
 wanec_api_monitor_t *monitor);
Parameters
devname Sangoma wanpipe device name (like wanpipe1 or wanpipe2).
verbose Verbose mode [0|1|2].
wanec_api_monitor_t
fe_chan int
If the value set to 0, the function will read monitored data from EC
chip. Otherwise, the function will start record monitored data for
specified channel.
Appendix A
/* Echo Canceller channel operation modes */
WANEC_API_OPMODE_NORMAL:
Echo Canceller operation mode is enabled.
WANEC_API_OPMODE_HT_FREEZE:
This mode prevents the AF from updating its echo-path
mode (used for validation test such as G.168).
WANEC_API_OPMODE_HT_RESET:
This mode clears the echo-path model.
WANEC_API_OPMODE_POWERDOWN:
This mode puts Echo Canceller in bypass mode.
WANEC_API_OPMODE_NO_ECHO:
This mode allows voice quality features to be used
without performing echo cancellation.
WANEC_API_OPMODE_SPEECH_RECOGNITION:
This mode is used when echo cancellation needs to be
enabled but not the NLP.

/* Echo Canceller port definition */

WAN_EC_CHANNEL_PORT_SOUT:
Outgoing port from Echo Canceller chip to PCI bus.
WAN_EC_CHANNEL_PORT_SIN:
Incoming port into Echo Canceller chip from PCI bus.
WAN_EC_CHANNEL_PORT_ROUT:
Outgoing port from Echo Canceller chip to remote side
WAN_EC_CHANNEL_PORT_RIN:
Incoming port into Echo Canceller chip from remote side.
Appendix B
This is list of Echo Cancellation chip parameters:

Chip parameter Chip parameter value

WANEC_TailDisplacement 0-896
WANEC_MaxPlayoutBuffers 0-4678
WANEC_EnableExtToneDetection TRUE | FALSE
WANEC_EnableAcousticEcho TRUE | FALSE

This is list of Echo Cancellation channel parameters:

Channel parameter Channel parameter value

WANEC_EnableNlp TRUE | FALSE
WANEC_EnableTailDisplacement TRUE | FALSE
WANEC_TailDisplacement 0-896
WANEC_SoutLevelControl TRUE | FALSE
WANEC_SoutLevelControlGainDb -24 - 24
WANEC_RinAutomaticLevelControl TRUE | FALSE
WANEC_RinAutomaticLevelControlTargetDb -40 – 0
WANEC_SoutAutomaticLevelControl TRUE | FALSE
WANEC_SoutAutomaticLevelControlTargetDb -40 – 0
WANEC_SoutAdaptiveNoiseReduction TRUE | FALSE
WANEC_RoutNoiseReduction TRUE | FALSE
WANEC_ComfortNoiseMode COMFORT_NOISE_NORMAL
COMFORT_NOISE_FAST_LATCH
COMFORT_NOISE_EXTENDED
COMFORT_NOISE_OFF
WANEC_DtmfToneRemoval TRUE | FALSE
WANEC_AcousticEcho TRUE | FALSE
WANEC_NonLinearityBehaviorA 0-13
WANEC_NonLinearityBehaviorB 0-8
WANEC_DoubleTalkBehavior DT_BEH_NORMAL
DT_BEH_LESS_AGGRESSIVE
WANEC_AnrSnrEnhancementDb -9,-12,-15,-18,-21,-24,-27 or -30dB
Revision History
Version Revision Description
0.1 Oct 20, 2007 Initial version
0.2 Nov 10, 2007 • Add support for all EC Operation modes.
• Add more custom Echo Canceller parameters.
• Replace tone_load/tone_unload to
buffer_load/buffer_unload. Also, structure
tone_config is replaced by buffer_config.
• Add notifyonstop parameter to
wanec_api_playout_t structure.
0.3 Dec 06, 2007 • Add following custom parameters:
lRinAutomaticLevelControlTargetDb
lSoutAutomaticLevelControlTargetDb
lSoutLevelControlGainDb
lAnrSnrEnhancementDb