Program Documentation

Abstract

sip-mbus controller provides the functionality which can control RAT for sipc. sip-mbus controller allows sipc 1) to initialize mbus library, 2) to change remote ip address, 3) to enable/disable to mute/talk of RAT, 4) to change the codec of RAT, 5) to choose the packetization rate, 6) to control the volume and gain of speaker and microphone and 7) to make RAT to be quit for RAT user interface hidden.

Installation instructions

This explain is for Unix compatible O/S. In Windows compatible O/S, Visual C++ can be used.

RAT

When rat-4.2.12.tar.gz is extracted from the archive, it makes four directories, common, rat, tcl-8.0 and tk-8.0. common directory contains mbus library source code. The patch directory has two files (rtp.c and rtp.h) in common directory and they should be overwritten and then compile them.

$ cp patch/common/* $(RAT-DIRECTORY)/common

$ ./configuration

$ make

tcl-8.0 and tk-8.0 directories have tcl/tk source code for mbus library engines, media and user interface of RAT.

$ ./configuration

$ make

rat directory have source code for controller, engine and user interface for RAT. The patch directory has two files (mbus_engine.c and ui_audiotool.tcl) which need to be overwritten. They were added to process rtp.addr.change mbus command.

$ cp patch/rat/* $(RAT-DIRECTORY)/rat

$ ./configuration

$ make

sip-mbus controller

In Unix:

$make /f makefile.unix

This command will make several directories which are obj for object files and unix for library files. The test programs are in the test directory.

Operation

sip-mbus interface

sip-mbus interface Description

sipc_mbus_control NAME

sipc_mbus_control - initialize the mbus library

SYNOPSIS

#include "sip_mbus_control.h"

int sipc_mbus_control(ClientData dummy, Tcl_Interp *interp, int argc, char **argv);

The sipc_mbus_control() function provides for initialization of mbus library.

The argv[1] argument is NULL.

sip_mbus_rtp_addr NAME

sip_mbus_rtp_addr - change the remote IP address, src/dst port number and ttl of RAT

SYNOPSIS

#include "sip_mbus_control.h"

int sipc_mbus_rtp_addr(ClientData dummy, Tcl_Interp *interp, int argc, char **argv);

The sipc_mbus_rtp_addr() function provides for control over IP address, port number and ttl.

The sipc_mbus_rtp_addr takes four arguments.

argv[1] remote IP address

argv[2] source port number

argv[3] destination port number

argv[4] time-to-live

sipc_mbus_talk NAME

sipc_mbus_talk - enable/disable of talk

SYNOPSIS

#include "sip_mbus_control.h"

int sipc_mbus_talk(ClientData dummy, Tcl_Interp *interp, int argc, char**argv);

The sipc_mbus_talk() function enables or disables of talk of RAT.

The sipc_mbus_talk takes one argument.

argv[1] 0: talk, 1: mute

sipc_mbus_codec NAME

sipc_mbus_codec - changes the codec

SYNOPSIS

#include "sip_mbus_control.h"

int sipc_mbus_codec (ClientData dummy, Tcl_Interp *interp, int argc, char**argv);

The sipc_mbus_codec () function changes the codec of RAT to encode.

The sipc_mbus_codec takes one argument.

argv[1]

l16:        Linear 16, 128 kbit/s: Uncompressed 16 bit samples

pcma:   A-Law, 64 kbit/s: a-law companded 8 bit samples

pcmu: Mu-Law, 64 kbit/s: mu-law companded 8 bit samples.

dvi:       DVI-ADPCM, 32 kbit/s: 16 bit samples.

gsm:    GSM, 13.2 kbit/s:

lpc: LPC, 5.8 kbit/s

sipc_mbus_packetization NAME

sipc_mbus_packetization - sets the number of codec frames

SYNOPSIS

#include "sip_mbus_control.h"

int sipc_mbus_codec (ClientData dummy, Tcl_Interp *interp, int argc, char**argv);

The sipc_mbus_codec () function sets the number of "units" (codec frames, typically) placed in each packet when transmitting.

The sipc_mbus_codec takes one argument.

argv[1]: units: 1, 2, 4 or 8

sipc_mbus_input_gain

NAME

sipc_mbus_input_gain - controls the gain of microphone

SYNOPSIS

#include "sip_mbus_control.h"

int sipc_mbus_input_gain (ClientData dummy, Tcl_Interp *interp, int argc, char**argv);

The sipc_mbus_input_gain () function turn up or down the gain of the microphone.

The sipc_mbus_input_gain takes one argument.

argv[1]: gain, percentage value

sipc_mbus_output_gain

NAME

sipc_mbus_output_gain - controls the volume of speaker

SYNOPSIS

#include "sip_mbus_control.h"

int sipc_mbus_output_gain (ClientData dummy, Tcl_Interp *interp, int argc, char**argv);

The sipc_mbus_output_gain () function turn up or down the gain of the speaker.

The sipc_mbus_output_gain takes one argument.

argv[1]: gain, percentage value

sipc_mbus_rat_quit

NAME

sipc_mbus_rat_quit - makes RAT to be quit

SYNOPSIS

#include "sip_mbus_control.h"

int sipc_mbus_rat_quit (ClientData dummy, Tcl_Interp *interp, int argc, char**argv);

The sipc_mbus_rat_quit () function makes RAT to be quit without using the user interface of RAT.

The sipc_mbus_rat_quit takes no arguments.

Program internal operation

sipc should spawn sip-mbus controller (sip_mbus_control.c) to send and receive mbus command to and from RAT before it uses mbus library (mbus_control.c). The sip-mbus controller not only sends mbus.hello mbus command as a heartbeat message every second to indicate liveness, but also receives mbus.hello of other mbus engines.

sipc_mbus_control

This function should be called before other mbus-controller function calls because this initialize the mbus library. sipc_mbus_control calls sip_mbus_control() function which initializes the mbus library and sends mbus.hello command and receives it periodically.

void sip_mbus_control () {

    /* create the mbus address of sip-mbus controller */

    /* initialization of mbus library */

    mbus_init(mbus_control_rx, mbus_err_handler, c_addr);

    while (true) {

        /* send mbus.hello command */

         mbus_send(m);

        /* mbus handler process the received mbus command */

        mbus_recv(m, m, &timeout);

    }

}

sip_mbus_rtp_addr

sipc sends rtp.addr.change mbus command calling rtp_addr_change() of sip-mbus controller to change remote IP address, src/dst port number and ttl. Before it sends the command, it should encode them using mbus_encode_str() function. This command should be sent to the mbus_engine of RAT. If this command is being sent to user interface or controller of RAT, they will be exit abnormally.

mbus_qmsgf (mbus, addr_rat_engine, reliable, mbus_command, "%s %d %d %d", ip_addr, src, dst, ttl);

mbus: mbus library

addr_rat_engine: the mbus address of the mbus engine of RAT

reliable: TRUE or FALSE

mbus_command: rtp.addr.change mbus command

arguments: encoded string of "ip-addr src_port dst_port ttl".

sipc_mbus_talk, sipc_mbus_codec, sipc_mbus_packetization, sipc_mbus_input_gain, sipc_mbus_output_gain and sipc_mbus_rat_quit

All procedure is similar to rtp_addr_change() function except using different mbus commands.

sipc_mbus_talk: audio.input.mute

sipc_mbus_codec: tool.rat.codec

sipc_mbus_packetization: tool.rat.rate

sipc_mbus_input_gain: audio.input.gain

sipc_mbus_output_gain: audio.output.gain

sipc_mbus_rat_quit: mbus.quit

mbus library

In order to provide the functionality of address change for RAT, some RAT source files are changed.

RAT source files

mbus_engine.c

This static table maps the mbus command rtp.addr.change to rx_rtp_addr_change() function. When mbus engine of RAT receive rtp.addr.change mbus command, it calls rx_rtp_addr_change() function, which uses rtp_addr_change() function in mbus library.

static const mbus_cmd_tuple engine_cmds[] =
{ .....
{"rtp.addr.change", rx_rtp_addr_change },
.....

static void rx_rtp_addr_change(char *srce, char *args, session_t *sp)
{
     /* rtp.addr.change ("224.1.2.3" 1234 1234 16) */
     char    *addr;
     int      rx_port, tx_port, ttl;
     struct mbus_parser      *mp;

     UNUSED(srce);

     mp = mbus_parse_init(args);
     mbus_parse_str(mp, &addr); addr = mbus_decode_str(addr);
     mbus_parse_int(mp, &rx_port);
     mbus_parse_int(mp, &tx_port);
     mbus_parse_int(mp, &ttl);
     mbus_parse_done(mp);

     tx_stop(sp->tb);

    // close the existing session
     rtp_send_bye(sp->rtp_session[0]);
     rtp_done(sp->rtp_session[0]);
     rtp_callback_exit(sp->rtp_session[0]);

     pdb_item_destroy(sp->pdb, rtp_my_ssrc(sp->rtp_session[0]));

     ui_send_rtp_remove(sp, sp->mbus_ui_addr, rtp_my_ssrc(sp->rtp_session[0]));

    // make a new session using new ip address, ports and ttl
     sp->rtp_session[0] = rtp_init(addr, (uint16_t)rx_port, (uint16_t)tx_port, ttl, 64000, rtp_callback, NULL);
     rtp_callback_init(sp->rtp_session[0], sp);


     ui_send_rtp_addr(sp, sp->mbus_ui_addr);

     if(sp->rtp_session_count < sp->layers && sp->rtp_session_count > 0) {
         rtp_set_my_ssrc(sp->rtp_session[0], rtp_my_ssrc(sp->rtp_session[0]));
     }
}

ui_audiotool.tcl

This file is related to user interface of RAT. If it receive rtp.addr.change mbus command, it updates the user interface using this procedure.

proc mbus_recv_rtp.addr.change {addr rx_port tx_port ttl} {
global session_address group_addr
set group_addr $addr
set session_address "Address: $addr Port: $rx_port TTL: $ttl"
}

When SIPC connects to the destination host or phone, the user interface of RAT had better not showed up. In order to hide the user interface, the two lines including wm deiconify in ui_audiotool.tcl can be comment out if you want to.

proc mbus_recv_session.title {title} {
    global session_title tool_name
    set session_title \"$title\"
    wm title . "$tool_name: $title"
    #    wm deiconify .
}

proc toggle_plist {}{

....

# wm deiconify .

At this case, it is no way to control the volume of microphone and speaker of RAT and to make RAT be quit, SIPC has to provide those functionality to the user.

Test

The test directory contains two test programs. The test1.tcl uses hard coded values of the parameters and just tests whether mbus library works. The test2.tcl provides the user interface to get user input for RAT. Please be sure RAT execution before the test program.

$test1.tcl

This test program check out the working of the sip-mbus controller.

$test2.tcl

Tk interface is provided to get user input for remote IP address, codec, mute/talk parameter and packetization values.

When RAT executes, the following figure shows that the remote IP address is "128.59.15.51", source/destination port numbers are 23456, mute of talking and ttl is 15.

Test1 program allows you to change the parameters of RAT. If the parameters in the test2.tcl are sent to RAT, the next figure is the result.

If RAT gets mbus commands from sip-mbus controller, such as tool.rat.codec etc., it updates its user interface and the mbus configuration parameters. The UI component of RAT updates the user interface and engine component of RAT modifies rtp sessions and internal data structure for the operation of RAT.

Source Codes

All source files are sip-mbus.tar except RAT related files. RAT can be downloaded at Reliable Audio Tool (RAT)

Last updated 02/16/01

sip-mbus interface	Description
sipc_mbus_control	NAME sipc_mbus_control - initialize the mbus library SYNOPSIS #include "sip_mbus_control.h" *int sipc_mbus_control(ClientData dummy, Tcl_Interp interp, int argc, char argv); The sipc_mbus_control() function provides for initialization of mbus library. The argv[1] argument is NULL.
sip_mbus_rtp_addr	NAME sip_mbus_rtp_addr - change the remote IP address, src/dst port number and ttl of RAT SYNOPSIS #include "sip_mbus_control.h" *int sipc_mbus_rtp_addr(ClientData dummy, Tcl_Interp interp, int argc, char argv); The sipc_mbus_rtp_addr() function provides for control over IP address, port number and ttl. The sipc_mbus_rtp_addr takes four arguments. argv[1] remote IP address argv[2] source port number argv[3] destination port number argv[4] time-to-live
sipc_mbus_talk	NAME sipc_mbus_talk - enable/disable of talk SYNOPSIS #include "sip_mbus_control.h" *int sipc_mbus_talk(ClientData dummy, Tcl_Interp interp, int argc, charargv); The sipc_mbus_talk() function enables or disables of talk of RAT. The sipc_mbus_talk takes one argument. argv[1] 0: talk, 1: mute
sipc_mbus_codec	NAME sipc_mbus_codec - changes the codec SYNOPSIS #include "sip_mbus_control.h" *int sipc_mbus_codec (ClientData dummy, Tcl_Interp interp, int argc, charargv); The sipc_mbus_codec () function changes the codec of RAT to encode. The sipc_mbus_codec takes one argument. argv[1] l16: Linear 16, 128 kbit/s: Uncompressed 16 bit samples pcma: A-Law, 64 kbit/s: a-law companded 8 bit samples pcmu: Mu-Law, 64 kbit/s: mu-law companded 8 bit samples. dvi: DVI-ADPCM, 32 kbit/s: 16 bit samples. gsm: GSM, 13.2 kbit/s: lpc: LPC, 5.8 kbit/s
sipc_mbus_packetization	NAME sipc_mbus_packetization - sets the number of codec frames SYNOPSIS #include "sip_mbus_control.h" *int sipc_mbus_codec (ClientData dummy, Tcl_Interp interp, int argc, charargv); The sipc_mbus_codec () function sets the number of "units" (codec frames, typically) placed in each packet when transmitting. The sipc_mbus_codec takes one argument. argv[1]: units: 1, 2, 4 or 8
sipc_mbus_input_gain	NAME sipc_mbus_input_gain - controls the gain of microphone SYNOPSIS #include "sip_mbus_control.h" int sipc_mbus_input_gain (ClientData dummy, Tcl_Interp interp, int argc, charargv); The sipc_mbus_input_gain* () function turn up or down the gain of the microphone. The sipc_mbus_input_gain takes one argument. argv[1]: gain, percentage value
sipc_mbus_output_gain	NAME sipc_mbus_output_gain - controls the volume of speaker SYNOPSIS #include "sip_mbus_control.h" int sipc_mbus_output_gain (ClientData dummy, Tcl_Interp interp, int argc, charargv); The sipc_mbus_output_gain* () function turn up or down the gain of the speaker. The sipc_mbus_output_gain takes one argument. argv[1]: gain, percentage value
sipc_mbus_rat_quit	NAME sipc_mbus_rat_quit - makes RAT to be quit SYNOPSIS #include "sip_mbus_control.h" int sipc_mbus_rat_quit (ClientData dummy, Tcl_Interp interp, int argc, charargv); The sipc_mbus_rat_quit* () function makes RAT to be quit without using the user interface of RAT. The sipc_mbus_rat_quit takes no arguments.