TDM SDK Overview

Sangoma TDM SDK Overview

Sangoma TDM SDK is composed of number of low level libraries.

• Sample Applications

  • Sample applications to be used by customers to Quick Start their projects

• Unified Signalling and Media Framework: FreeTDM

  • Sangoma proprietary telco grade TDM Protocol Stacks: PRI,BRI,SS7,GSM,FXO,FXS

  • Tone and DTMF libraries

  • Statistics and Alarms

• Sangoma Hardware Operation Library

  • Hardware Detect

  • Port Configuration

  • Port Start/Stop

• Sangoma Wanpipe Device Driver Suite 
  
  

  • Low level Sangoma Driver API: LibSangoma

  • Linux and Windows kernel drivers

  • (Installed separately from Sangoma SDK)
    
    

File Structure

Sangoma TDM SDK file structure is separated into two sections

• applications

  • location of fully working sample applications

  • these files are to be used as starting point in application development

  • customers are encouraged to edit/change and use sample code in their applications

• applications / common

  • the common directory contains helper functions that are used in sample and
    customer applications. 

  • Customers should NOT edit these files, but use them as they are. 

  • Content of the common files WILL change in future SDK releases while preserving the API compatibility.

  • Sangoma HW Operation Interface

  • Sangoma FreeTDM Config Interface

• lib

  • Sangoma SDK Libraries

  • These are Sangoma private libraries that should not be modified by customers

  • Content of the lib files WILL change in future SDK releases while preserving the API compatibility.

TDM SDK Flow

The call flow below maps the above SDK sections to the application call flow.

Typical application call flow

• Start user application

  • This is application main code.

• Initialize Sangoma SDK

  • Call to the common helper code to initialize libsangoma and freetdm framework

  • Setup callbacks 
    
    

    • Callbacks are functions that are defined in Customer application

    • These functions are passed to the common and library code and are called
      at a specific time when appropriate by the Sangoma SDK.

    • eg: hwprobe for each hw prot detected

• Detect sangoma hardware

  • The common code will confirm that Sangoma device drivers are loaded.
    This instructions assumes that Sangoma device drivers are already installed.

  • The common code helper function will use libsangoma calls to iterate over detected hardware.

  • For each hw port detected helper function will create a Sangoma Port Object and call back the user application.
    Sangoma Port Obect is an opaque object that can be accessed using sangoma common helper functions.
    It contains all sangoma hw port information as well as configuration structures needed to start,stop,query the hw port,

• For each hw port detected

  • Sangoma SDK will call the hw probe callback functions into the user application

  • User application should

    • Determine board type and port number

    • Stop hw port

    • Configure hw prot using Sangoma SDK configuration functions

    • Start hw port

    • Create the FreeTDM span using hw port information

    • Configure the FreetDM span using hw port information

    • Start the FreeTDM span 
      
      

      • Which will launch the thread in FreeTDM framework on start signalling on the sangoma hw port.

      • At this point FreeTDM will wait for events such as

        • Link up, Incoming Call, Alarm, etc...

• Event Handling

  • At this point all Sangoma ports have been started and FreeTDM is running on each hw port.

  • FreeTDM will listen for events generated by signaling protocol or sangoma hw.

  • Customer application needs to launch a Event Handling thread to handle all FreeTDM events.
    The common helper functions implement the queuing mechanism that will send all FreeTDM events
    to the customers Event Handling thread.

  • Event Handling thread will wait on the queue for FreeTDM events to arrive.

• Main Menu

  • At this point the main thread can just sit idle or do other user defined tasks.

  • In GSM custom application a small user menu has been created to allow a user to execute GSM commands

    • Place GSM Call

    • Send SMS

    • View GSM port statistics and status

    • The above commands use FreeTDM API defined in freetdm.h header fine.

• FXO/PRI/BRI/SS7 Tapping: Event Handler

  • The event handler thread in the custom FXO/PRI/BRI/SS7 application is listening on FreeTDM events.

    • Detect Call Start

    • Receive Caller ID

    • Start recording to file

    • Detect Hangup

    • Stop recording to file 
       

• GSM IVR Sample: Event Handler

  • The event handler thread in the custom GSM application is listening on FreeTDM events.

  • On incoming call event
    
    

    • The Event handler will launch a Media I/O thread to handle the GSM channel.

      • This is a design choice.  
        Event handler could have handled all the media in the Event thread.

    • The Media thread will call FreeTDM API to answer the call, and proceed into media handle loop.

    • It will read data from the FreeTDM voice channel in G711 codec format.

    • It then write the same data back to the FreeTDM channel

    • Thus the caller will hear his own voice. i.e. echo application.

    • The Media thread can

      • Read from the channel

      • Write to the channel

      • Read events from the channel
        Such as DTMF or SMS

  • On call hangup event

    • The Media thread will close the FreeTDM channel and exit.

  • Place Call

    • If the user places a call using the Main Menu

    • The Event handler will receive a connect event which also indicates that the call has been established.

    • At that point the same scenario will occour as for the incoming call event.

•  Note that Green Box: FreeTDM is a single library, its displayed as two boxes due to spacing limitations of the flowchart :)

Sangoma FreeTDM Background

Threads

• Sangoma FreeTDM is a threaded library.

• All FreeTDM API's are thread safe.

Blocking

• By default all FreeTDM API calls are blocking.

• This means that they delay current process/thread operations until 
  the low level FreeTDM state changes complete.
  The API command delys are usually in milliseconds.

Reading

• As per comment above, the read api is blocking.
  If user runs a read command it will block until data arrives.
  This is ok in a "Thread per call/channel mode" 
  However care must be taken if a single thread is used to handle multiple channel.
  
  

• A recommended solution to a blocking read is to use a Poll function.
  The poll function will wait for Read, Write or Event.
  Furthermore, the poll wait function can also timeout if processing is needed.

Event Handling

• FreeTDM waits for signaling, media or alarm events.

• On event FreeTDM will call back the user application.

• A RULE: is that no FreeTDM API command is allowed from FreeTDM Event Callback.

• For this reason the sample application contains a queue and a application event handling thread.

• On FreeTDM Event callback, the event is copied and passed to the queue.

• The application event handling thread will dequeue the message and process FreeTDM Event

  • Events such as call start, hangup etc..

• User is allowed to execute FreeTDM API command from application event handling thread.

Application Threading Model

• Its highly recommended that customers adopt Thread per Call/Channel model

  • In this mode, the code becomes very simple as it only has to handle one channel object.

  • Poll, Read, Write, Event per channel object

• In some scenarios this is not possible to have this mode due to legacy application design.

  • Running all media and signaling from single thread is never a good idea.

  • However using Poll function to listen to multiple channels will usually suffice and the FreeTDM API blocking
    would usually be too small to notice.

  • In some very rare cases NON blocking is needed
    
    

    • FreeTDM does support non blocking calls, but its not explained in this documentation.