LibSangoma Voice API

Owned by Nathaniel Halbrooks
Last updated: Mar 26, 2024 by Kelli Higdon
6 min read

Overview

WANPIPE® TDM Voice API: LibSangoma is a device based, multi-threaded suite of kernel drivers and user space libraries (LibSangoma) that can be used to build custom Voice applications over TDM Voice hardware, on both Linux & Windows.

The WANPIPE® TDM Voice API has been designed to fit easily into a network programming model. Therefore, anyone who has ever done any socket programming will feel right at home. Thanks to the socket API model, a channel on a particular span is just a file descriptor that can be used to transmit and received voice data. Along with standard Rx/TX, a tdm device also supports OOB messages that become useful in DTMF detection and RBS signaling. Standard IOCTL calls are used to control channel socket parameters such as rx/txperiod, codec control, echo control, Rbs and dtmf.

The WANPIPE® TDM Voice API is supported on Linux & WIndows.  Furthermore, all sample codes are identical for all operating systems.

 

Sangoma Wanpipe TDM API Architecture:

 

Sangoma Wanpipe TDM API Provides:

  • Support for Linux & Windows operating systems.  

  • Common API for all Sangoma Hardware (T1/E1/Analog/BRI).

  • Extensive Support for TDM Voice Applications

  • SPAN API Mode  -  one device per span (TDM Voice or WAN Data)

  • CHAN API Mode -  one device perchan  (TDM Voice Only)  

  • Timer Devices used for Timing

  • Global Config Device used to configure/control/debug.

  • Global Control Device receives all events from all devices.

  • LibSangoma (Library/DLL) - Abstracts all OS API calls.

Sangoma Wanpipe TDM API Components:

  • WanpipeKernel Driver & Utilties - Common for Linux & Windows

  • LibSangoma API Library/DLL

 

WANPIPE® Voice API

  • libsangomais a device based, multi-threaded suite of kernel drivers and user space libraries that is used to build custom Voice applications over Sangoma TDM Voice hardware, on both Linux & Windows.

LibSangoma

  • Is a user space library (.so/.dll)

  • Abstracts Linux and Windows systemcallsintoaOS agnostic API

  • Provides a common API for all Sangoma hardware.

  • Is a very low level “RAW” API. It has not logic or state machines.

  • Providesgreatest flexibilityfor a developer, consequently itshardestto use.

LibStelephony

  • Is a helper user space library (.so/.dll)

  • implementsvoice processing:callerid, dtmf

  • Implements PRI decoding

 

 

Installation

Wanpipe TDM Voice API Solution 

  1. Wanpipe Release -> Download Here
    -> TDM API Driver
    -> LibSangoma User Library -> user space API.

 

Wanpipe TDM Voice API is currently supported on all AFT hardware.

 

Wanpipe Package Installation

  1. Untar LATEST release  

    tar xvfz wanpipe-<version>.tgz

     

  2. Change directory into wanpipe source directory

    cd wanpipe-<version>/

     

  3. Compile and install wanpipe driver

    make make install

     

  4. To confirm successful installation run:

     

Wanpipe Package Configuration

 

Wanpipe drivers can be configured for 3 API modes

  1. TDM SPAN Mode

    Run: /usr/sbin/wancfg_span_tdmapi
    -> Each board will configure the span for voice only mode or voice + dchan. 

    -> Furthermore, Sangoma TDM SPAN API supports multiple DCHANS  so on can configure  
        channels 1-10 as voice and 11-24 as HDLC DCHANS.

     

  2. TDM CHAN Mode

    Run: /usr/sbin/wancfg_tdmapi
    -> Each board will configure the span for voice only mode or voice + dchan.
    -> Furthermore, Sangoma TDM API supports multiple DCHANS  so on can configure  
        channels 1-10 as voice and 11-24 as HDLC DCHANS. 

     

  3. DATA API Mode

    Run: /usr/sbin/wancfg_data_api
    -> For each card wancfg_data_api will configure the span for voice only mode or voice + dchan. 
    -> Furthermore, TDM API supports multiple DCHANS  so on can configure  
        channels 1-10 as voice and 11-24 as HDLC DCHANS.

 

Note: For full description of wanpipe1.conf files please refer to attached samples below.

 

Wanpipe TDM API Startup & Operation

Once the above wanpipe port configuration is complete using wancfg_tdmapi configuration utility. One has to start all ports.

  1. ->This command will load and configure wanpipe drivers
    -> For full wanrouter usage click here  

  2. Full driver log and events are located in /var/log/messages
    ->

  3. At this point TDM driver is configured and ready to tx/rx voice & dchan data.  One must make sure that ports are in connected state before trying to tx/rx data using the API programs.
    -> wanrouter status                           #check status of all ports
    -> wanpipemon -i w1g1 -c Ta            #check T1/E1 alarms of each port  

  4. Once all ports are connected the ifconfig command can be used to confirm that card running.
    -> ifconfig 
        The rx/tx data packets should be incrementing
        The MTU value indicates the hardware chunk size
        Any rx or tx errors indicate that something is wrong with the data flow.
           -> overruns   : indicate dma problems  or mis-configured system.

 

Wanpipe TDMAPI Sample Code

Note: the /etc/wanpipe directory is created after wanpipe package installation.

Sample code for tdm api is installed in /etc/wanpipe/api/tdm_api directory.

  1. cd /etc/wanpipe/api/tdm_api
    or
    cd /etc/wanpipe/api/libsangoma/examples/

  2. Read the README file on how to use sample applications

 

Wanpipe TDMAPI priserver Sample Code

The priserver sample code combines simple tdm_api sample file with libpri library.

The priserver is located in /etc/wanpipe/api/libsangoma/examples directory.

  1. cd /etc/wanpipe/api/libsangoma/examples

  2. make clean

  3. make

  4. make install

Note: if you get a compilation error with priserver you have not compile libsangoma with the libpri support. Pleaser refer to installing libsangoma with libpri below.

 

TDM API Sample Code  Usage

  1. aft_tdm_hdlc_test 

    This application is used to tx/rx HDLC data to and from a voice or dchan.  It is useful as a CRC data test to confirm that all voice & dchan channels are working free of bit errors.

    ->./aft_tdm_hdlc_test  wanpipe1 <span-chan device> <span-chan device> ....

    ->eg: ./aft_tdm_hdlc_test wanpipe1 s1c1 
              Start hdlc tx/rx on span 1 chan 1 

     

    ->eg:  ./aft_tdm_hdlc_test wanpipe1 s1c1 s1c2
              Start hdlc tx/rx on both span 1 chan 1 and span 1 chan 2  

    With this application one can test the full card by specifying all spans and chans on the command line.
    A small script is included in this directory that can simplify the use to this application
    -> ./tdm_hdlc_test.sh  "span list"  "chan list"
       
    -> eg: ./tdm_hdlc_test.sh  1 1            # Start hdlc test on span 1 chan 1
              ./tdm_hdlc_test.sh   "1 2" 1      # Start hdlc test on chan 1 of span 1 & 2
              ./tdm_hdlc_test.sh   1              # Start hdlc test on all chans for span 1   

 

Wanpipe TDM API in Production - Sangoma Media Gateway SMG

The Sangoma Media Gateway has been built on TDM API. Once can look at the the production code to see how one would use the TDM API to build a full media gateway applicatoins.

The Sangoma Media Gateway is located in every wanpipe release

  1. cd wanpipe-<version>

  2. cd ssmg/sangoma_mgd.trunk

  3. vi sangoma_mgd.c
    -> search for all instances of "sangoma_"  these are all 
        libsangoma api functions used in the media gateway.

 

 

Wanpipe LibSangoma Installation

 

Libsangoma is installed automatically during the installation process!
These instructions are here for information sake, in case one wants to recompile libsangoma library.

The LibSangoma is installed in /etc/wanpipe/api/libsangoma

  1. cd /etc/wanpipe/api/libsangoma

  2. ./configure

  3. make

  4. make install

  5. Add library path /usr/local/lib into /etc/ld.so.conf

  6. Run ldconfig to accept /etc/ld.so.conf changes.

 

Wanpipe LibSangoma with LibPRI Installation (Optional must be done manually)

  1. Download  libpri from www.asterisk.org and save it into /usr/src directory.

  2. Untar libpri tgz file in /usr/src directory

  3. Change directory into libpri and run: make; make install

  4. cd /etc/wanpipe/api/libsangoma

  5. ./configure  --with-libpri=/usr/src/<libpri directory>

  6. make

  7. make install

  8. Add library path /usr/local/lib into /etc/ld.so.conf

  9. Run ldconfig to accept /etc/ld.so.conf changes.

Sample API configuration Files

-> Voice API Configuration file:
-> Analog Voice API Config:
-> PRI-mode Voice API Config:     
-> PRI-datascope-tap-mode:

 

 

API Documentation

LibSangoma proves OS abstraction to Wanpipe Driver Voice & Data API system calls.  It contains all Wanpipe Driver Voice & Data API functions, abstracted for Linux & Windows so that user application remains OS independent.

  1. Doxygen LibSangoma Documentation


LibSangoma Components

  • Configuration Functions
    configure T1/E1, analog, BRI ports before they are started or restarted

  • System Operation Functions
    used to start, stop, restart Sangoma tdm ports

  • IO Operation Functions
    used to open, close, read, write,poll on bchan or dchan devices
    set events that relate to IO or call setup
    callerid, on-hook, off-hook, rbs etc…

  • Event Functions
    used to read events from bchan or dchan devices.
    Used to enable or disable hw events (DTMF, Fax events …)

  • Statistic Functions
    used to read hw and driver statistics.
    Operational, Hardware, Error, IO, statistics

 

LibSangoma IO Componnets

  • SPAN Mode
    Single device per T1/E1 span.
    Data from a single span is passed up to a user as a single chunk of data.
    User has the responsibility to multiplex and de-multiplex data per channel.
    Better performance on higher densities.
    Harder to develop on.

  • CHAN mode
    Device per T1/E1 channel
    Highly efficient interrupt logic to minimize number of interrupts.
    High kernel context switching due to large number of devices.
    Easer to develop on. Easily fits into a multi-thread applications.
    Default behavior for Zaptel/DAHDI, FreeSWITCH, SMG

 

 

FAQ

Libsangoma EC Control

 

How to turn on/off Echo Canceller by calling libsangoma API

In libsangoma, the API can be called in this way (functions defined in libsangoma.h, and can be called from customer's source code directly to libsangoma):

/*!
  \fn int sangoma_tdm_enable_hwec(sng_fd_t fd, wanpipe_api_t *tdm_api)
  \brief Enable HWEC on this channel 
  \param fd device file descriptor
  \param tdm_api tdm api command structure
  \return non-zero: error, 0: ok
  
  Supported only on cards that have HWEC
*/
int _LIBSNG_CALL sangoma_tdm_enable_hwec(sng_fd_t fd, wanpipe_api_t *tdm_api);

/*!
  \fn int sangoma_tdm_disable_hwec(sng_fd_t fd, wanpipe_api_t *tdm_api)
  \brief Disable HWEC on this channel
  \param fd device file descriptor
  \param tdm_api tdm api command structure
  \return non-zero: error, 0: ok
  
  Supported only on cards that have HWEC
*/
int _LIBSNG_CALL sangoma_tdm_disable_hwec(sng_fd_t fd, wanpipe_api_t *tdm_api);

Example

The example to use the above APIs:

 

wanpipe_tdm_api_t tdm_api;
int err = 0;
memset(&tdm_api, 0, sizeof(tdm_api));
.......
err=sangoma_tdm_enable_hwec(ftdmchan->sockfd, &tdm_api);
err=sangoma_tdm_disable_hwec(ftdmchan->sockfd, &tdm_api);

 

Return to Documentation Home I Return to Sangoma Support