WANPIPEŽ Linux TDM Voice API

WANPIPE® TDM Voice API is a socket based, multi-threaded suite of kernel drivers and user space libraries that can be used to build custom Voice applications over TDM Voice hardware. 

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, tdm device also support OOB messages that become useful in DTMF detection and RBS signaling. Standard IOCTL calls are use to control channel socket parameters such as rx/tx period, codec control, echo control, rbs and dtmf.

Currently WANPIPE® TDM Voice API is only supported on Linux, however plans are in place to port the API to Windows and BSDs.

Diagram of WANPIPE® TDM Voice API

2006-02-07:  New TDM API release

Major Architectual changes using /dev/wptdm... architecture for each span chan.
Only supported on A104, A104D cards. 

WANPIPE® TDM Voice Device Model (Kernel Driver):

Voice Device for each voice channel on a particular span support:

Codecs: mLaw/aLaw/Slinear, codec control is done via IOCL calls.

Default Signalling: T1 = mLaw   E1 = aLaw
Configurable Codec:  SLinear/mLaw/aLaw

Where driver will encode default signalling to selected codec from hardware up the API and decode from selected codec to default signaling down to hardware.
This operaton can be perormed any time after socket is opened, but is usually done at the beginning of a call, once the socket/channel is opened.

Period: Support for adjustable voice sample period.

Using an IOCTL developer can adjust the rx/tx voice sample size at any time after opening a channel socket. (eg: 10ms, 20ms …). This is usually done at the beginning of a call, once the socket/channel is opened.

DTMF:  in-call dtmf detection.   (Supported)

All DTMF events are received via OOB messages and transmitted via IOCTL. Can be used for IVR development.

RBS: in-call rbs reception and transmission.  (Supported)

When working with channel banks, common signalling method used is RBS.  Where top bit on every channel is used to transmit control messages for that particular channel. 

Every  received RBS message will be passed to the user via OOB message, this way the voice data is never disrupted.  A developer can at any time transmit RBS control messages using an IOCTL command.

Echo cancallation: Supported by an IOCTL   (Supported)

Each channel on a particular span can enable or disable software/hardware echo cancellation on the fly.  This would usually be done during call startup. Furthermore in conjunction with EDAC one can confirm if echo exist or not, and then take appropriate action.

HDLC based device: signaling protocol that uses HDLC framing

An HDLC based signaling socket would attach to an HDLC channel on a particular span.  A developer would transmit and receive HDLC frames to and from hardware channel.

HDLC framed signaling protocols include PRI, ISUP etc...
A user space signaling library such as libpri or libISUP would be used in conjunction with an HDLC socket.

                       
Signaling: RBS:  (Supported)

RBS is very common in North America where PRI is not supported. The LSB of every voice stream is periodically modified to provide signaling information.
To avoid the problem where a user would have to open ALL channels in order to receive OOB RBS messages (as stated above in voice section), a special control socket, per span, can be setup to receive and tranmsit ALL RBS events for each channel in a span.

At any time a developer may transmit an RBS control message (setting or reading the ABCD RBS bits) to any channel using an IOCTL command.

Signalling DTMF:    (Supported)

When working with Analog hardware, special tones are used to facilitate control messages, such as incoming calls etc. These tones are known as DTMF and are transmitted/received on each channel.

To avoid the problem where a user would have to open ALL channels in order to receive OOB DTMF messages (as stated above in voice section), a special control socket, per span, can be setup to receive and tranmsit ALL DTMF events for each channel in a span.

At any time a developer can transmit a DTMF digit or read a DTMF digit associated with any channel using an IOCTL command.

LIBSANGOMA Library

TDMAPI Device Handling Open/Bind functions

int sangoma_open_tdmapi_span(int span);

Opens a first available chan on a span.
Return: file descriptor for opened channel.

Open a specific chan based on span/chan numbers .
Return: file descriptor for opened channel.

int sangoma_span_chan_toif(int span, int chan, char *interface)

Create an tdm api device name from span chan.
Return: Device name string in third argument.

int sangoma_span_chan_fromif(char *interface, int *span, int *chan)

Decodec span/chan numbers from device name.
Return: Span and Chan numbers in 2 and 3rd argument.

TDMAPI Device Rx/Tx functions

int sangoma_writemsg_tdm (int fd, void *tx_hdrbuf, int tx_hdrlen,
                                              void *databuf, int datalen, int flag);

Send a tx header +  tx data to channel device. The tx header can be in a different buffer from data. Tx header is used to send control information to a channel. Tx data is media content based on configured TDM sample period and codec used. 

int sangoma_readmsg_tdm (int fd, void *rx_hdrbuf, int rx_hdrlen,
                                             void *databuf, int datalen, int flag);

Receive an rx header + rx data buffer from a socket.  The rx header can contain channel control and statistics info. Rx data can contain a voice sample if this is a voice socket, based on configured sample period and codec used, or HDLC frame if this device is a PRI signalling channel.

Socket TDM API Commands per Channel

int sangoma_get_full_cfg(int fd, wanpipe_tdm_api_t *tdm_api)

Get Full TDM API configuration per chan.

int sangoma_tdm_set_codec(int fd, wanpipe_tdm_api_t *tdm_api, int codec);
int sangoma_tdm_get_codec(int fd, wanpipe_tdm_api_t *tdm_api);

Get/Set TDM Codec per chan.
Codec Options:  WP_NONE, WP_SLINEAR.

int sangoma_tdm_set_usr_period(int fd, wanpipe_tdm_api_t *tdm_api, int period)
int sangoma_tdm_get_usr_period(int fd, wanpipe_tdm_api_t *tdm_api)

Get/Set USR Tx/Rx Period in milliseconds.

int sangoma_tdm_get_usr_mtu_mru(int fd, wanpipe_tdm_api_t *tdm_api)

Get user MTU/MRU values in bytes. Before tx/rx on a device user would run this command to determine the exact packet size to transmit and receive. This function is only important on voice tdmapi devices.

int sangoma_tdm_set_power_level(int fd, wanpipe_tdm_api_t *tdm_api,
                                                         int power)
int sangoma_tdm_get_power_level(int fd, wanpipe_tdm_api_t *tdm_api)

Not supported yet

int sangoma_tdm_flush_bufs(int fd, wanpipe_tdm_api_t *tdm_api)

Flush buffers from current channel.

int sangoma_tdm_enable_rbs_events(int fd, wanpipe_tdm_api_t *tdm_api,
                                                            int polls_per_sec)
int sangoma_tdm_disable_rbs_events(int fd, wanpipe_tdm_api_t *tdm_api)

Enable TDMAPI RBS events on particular channel.  The enable function will pass in number of RBS polls per sec.  The minimum number of polls would be 20 and maximum 100. 
All RBS events will be received through OOB event.
Note: This function will be optimized using RBS Interrupt in next release.

int sangoma_tdm_read_event(int fd, wanpipe_tdm_api_t *tdm_api)

Read TDMAPI Events. This function must be executed after each OOB event. Each event handler must be initialized in order to be handled. Please refer to sample code.

int sangoma_tdm_write_rbs(int fd, wanpipe_tdm_api_t *tdm_api,
                                              unsigned char rbs)

At any time user can write RBS bits on a specifc channel. Standard Wanpipe devfinitions for A,B,C,D bits are: WPTDM_A_BIT, WPTDM_B_BIT, WPTDM_C_BIT, WPTDM_D_BIT