FreeTDM Sig & Voice API

1. Introduction
2. Installation
3. FreeTDM Configuration
4. FreeSWITCH Configuration
5. FreeSWITCH/FreeTDM operation
6. FreeTDM API
7. PDF Presentation
8. FreeTDM Presentation & Discussion

Introduction

FreeTDM is a signaling and board API abstraction used mainly by the FreeSWITCH project to place calls in TDM and analog telephony circuits. The library was previously named "OpenZAP". Sangoma has worked along with the FreeSWITCH developers in this library so Sangoma's customers can also use it to do custom development. The library is still under heavy development but the overall API does not change often. The intention of the library is to present a consistent API for different telephony signaling stacks and board I/O APIs.

FreeTDM can either be used as a standalone API or along with FreeSWITCH as an endpoint (mod_freetdm). If you want to use it as a part of FreeSWITCH remember following the FreeSWITCH configuration section.

Installation

The installation instructions depend on the operating system you use and whether you want FreeTDM as a standalone library or as a library used by FreeSWITCH.

Please go to the proper operating system web page and then continue with configuration afterwards.

Linux FreeTDM installation.

Windows FreeTDM installation.

FreeTDM Configuration

The configuration of FreeTDM spans is the same either for Linux or Windows, only the location of the freetdm.conf file changes.

The following instructions assume the default configuration directory for FreeTDM (in Linux /usr/local/freetdm/conf and for Windows at c:/freetdm/)

1. Edit freetdm.conf and remove everything there (the initial content is just a sample configuration for FXO/FXS channels). This is a sample configuration for 2 T1's meant to be used with Sangoma PRI stack.

[span wanpipe boostpri]
trunk_type => T1
group => sangoma1
b-channel => 1:1-23
b-channel => 2:1-23

The syntax for the span header is [span <io type> <span name>], where in this sample the I/O type is "wanpipe" and the span name is any string, in this case "boostpri".

The following is an explanation of the parameters:

trunk_type => Defines the type of span (channel container) to configure, what follows must be any of these values:  "E1", "T1", "J1", "BRI", "BRI_PTMP", "FXO", "FXS", "EM".

group => Sets the current dialing group name to use for any following "xx-channel" declaration that can be used to place calls like "b-channel, fxo-channel, fxs-channel" etc. Multiple "group" parameters may appear within the same [span] context to add channels to a different dialing group. This group name can then be used from a program via the FreeTDM API ftdm_channel_open_by_group() to select the first available channel to dial within a group.

b-channel => Channel range within a physical Wanpipe span. The format for this or any xx-channel configuration is <span>:<channel range begin>-<channel range end>. If no range is needed a single channel can be specified by omitting  the dash: <span>:<chan>.

Valid channel types: fxo-channel, fxs-channel, em-channel, b-channel, d-channel, cas-channel, b-channel.

However in this case no D-channel was specified because Sangoma PRI stack does not require it. For the particular case of spans to be used with boost (Sangoma PRI and BRI stacks) all channels must be added into a single logical span as shown in this configuration.

FreeSWITCH Configuration

The configuration of FreeTDM spans inside FreeSWITCH is the same for Linux and Windows. This is a sample configuration for 2 PRI spans using Sangoma PRI stack. The configuration must be placed in config/autoload_configs/freetdm.conf.xml inside FreeSWITCH directory. Important settings are in bold.

<configuration name="freetdm.conf" description="FreeTDM Configuration">
  <settings>
    <!--<param name="debug" value="0"/>-->
    <!--<param name="hold-music" value="$${moh_uri}"/>-->
  </settings>
  <boost_spans>
    <span name="boostpri">
      <param name="dialplan" value="XML" />
      <param name="context" value="default" />
    </span>
  </boost_spans>
</configuration>

The span "name" must match the name you specified in freetdm.conf. There is no PRI signaling parameters because those are configured in smg_pri.conf, for additional PRI parameters, see:

http://wiki.sangoma.com/wanpipe-pri-parameters

FreeSWITCH/FreeTDM operation

To start using FreeTDM you can either add the mod_freetdm module to the conf/autoload_configs/modules.conf.xml or load it manually with "load mod_freetdm" inside the FreeSWITCH CLI.

FreeTDM API

The FreeTDM API allows you to configure spans and run a given signaling stack on a span. The basic model of work is:

1. Initialize the library.
2. Load the configuration.
3. Configure a span providing the signaling stack to use, the parameters for that signaling (signaling specific parameters) and a function pointer to be used as callback to be notified about events.
4. Run the span. This will launch one or several background threads (depending on the signaling stack) where all the signaling work will be done for this span.
5. When you're done, your application must shutdown the stack, which will kill all the spans.

You can refer to libs/freetdm/src/testsangomaboost.c (which has plenty of comments) for a sample Sangoma boost program using the FreeTDM API.  There is also documentation in the main header file libs/freetdm/src/include/freetdm.h