The GSM IAP

This document describes the specifics of the GSM IAP. For a general description of an IAP, refer iap.html.

The GSM IAP provides an interface for the cell-phones in the testbed to be part of Iceberg (i.e., to be Iceberg end-devices, access Iceberg services, etc).

The constituent pieces

The GSM IAP is by far the most complicated one. It has several constituent pieces: the UPSim, the IP-PAD, and a Java-based software to interface the two to the Iceberg Internet-core. The relationship between these components is shown in the figure below.

The GSM IAP

The Java-based software is the UPSim-IP gateway in the picture. This software is very similar to the other IAPs. We will be describing this software in this document. For simplicity, we will use the term GSM-IAP to denote this software although the IAP also includes the other pieces in the figure.

The UPSim provides the control path between the cell-phone and the GSM-IAP. The IP-PAD (IP Packet Assembler Disassembler) provides the data-path. The data-path is in terms of an RTP stream per established session. The control-connection between the GSM-IAP and the UPSim is in terms of two TCP connections. This interface is documented elsewhere and is not relevant here.

Structure of the GSM-IAP

There are two main programs. One is the program that has the control connections with the UPSim -- Gsm_Iap.java. The other is the one that forwards the RTP stream from the IP-PAD to the other end of the session -- ctl_data.java. The interface between these two could have been an RMI interface. In fact, these need not have been different program -- the second could have been a thread within the first. But the interface between the two is a clumsy TCP based sockets interface (I was more familiar with sockets than Java RMI when I wrote this).

Gsm_Iap.java has five threads. There is one each for waiting on each of the TCP connections to the UPSim (one of the TCP connections is for calls from the cell-phone side, and one is for calls from the Internet-core side). One thread is for managing the TCP connection with ctl_data.java.

The other two threads are for reporting cell-phone attach and detach to an arbitrary interested party. This interface was originally intended for the preference registry to detect if a user's cell-phone is turned off and redirect calls accordingly. This interface is TCP based. There are a lot of open issues with such reporting and these have not been addressed very well. This part of the IAP needs re-thinking and re-implementation and can be ignored.

Interface between GSM-IAP and Ctl_Data Forwarder

The ctl_data forwarder connects to the GSM-IAP which listens on TCP port 2222. All further communication happens through this TCP connection. A uniform packet format is defined on this connection. The packet in C-style is:

struct ctl_data_pkt {
  byte type;
  byte ts;
  int send_port;
  int listen_port;
  int ipaddr;
};

The type field defines the purpose of the packet. The ts field specifies the time-slot of the call in question. The send_port and ipaddr define the destination of the packets on the other side. The listen_port field defines the port on which to listen locally for this particular stream.

The following packet types are defined:

• Start Command: This packet flows from the GSM-IAP to Ctl_Data and initiates a forwarder for a stream. The type field is 1. The ts field specifies the air time-slot of the call that has been setup with the cell-phone. One of the end points for the forwarder is defined by the time-slot: the machine is the IP-PAD (hardcoded) and the port is 1200 + 2*time-slot for incoming calls and 6000 + 2*time-slot for outgoing calls. The other end-point is given by the port and ipaddr fields. Note that the ipaddr is given as an integer (32 bits).
• Stop Command: This command stops the forwarder for the specified time-slot. Only the type (value 2) and ts slots are valid in this packet. This packet also flows from the GSM-IAP to the Ctl_Data program.
• Stopped Indication: This packet flows the Ctl_Data program to the GSM-IAP. It is an indication that a data stream has stopped. The type field is 3 and the ts field gives the time-slot of the relevant call. The forwarder program is supposed to timeout if it does not receive any packets for long. But such a timeout does not currently happen in the forwarder program. The original intention of this timeout was that the call should be dropped eventually if the other end crashes. But this should ideally be handled as part of a soft-state signaling protocol itself.

Note: When the GSM-IAP sets up a call to itself (one cell-phone to another), only one forwarder is required. This is spawned by the caller (that is, the IAP when it is calling, rather than when it is responding to the call).

The files

• Callto.java -- this is the program implementing the interface to be called by the APC and the CA.
• Gsm_Iap.java -- this is the main program during operation without a call agent. This is the one invoking the five threads mentioned previously.
• Serv_To_Upsim.java -- class to perform operations on one of the control connections with the UPSim (the one that handles calls/terminates to the cell-phones).
• serv_from_upsim.java -- class to perform operations on the other control connection with the UPSim (the one that handles calls/terminates/dtmf from the cell-phones).
• serv_ctl_data.java, ctl_data_pkt.java -- class to handle the TCP connection with the ctl_data program and the definition of the structure passed on the TCP connection.
• cs_class.java, call_state.java -- an individual call state and the collection respectively.
• upsim_pkt.java -- the structure of the packet that goes between the UPSim and the GSM-IAP over the control connections.
• ctl_data.java -- The program that handles the forwarding of the RTP streams.
• RegnThr.java, RegnSocket.java, AttachDetachThr.java -- classes to handle reporting of cell-phones registering and de-registering with the UPSim.
• upsim.java -- UPSim simulator for testing purposes.

Running the IAP

Since running the IAP without the other pieces (UPSim and IP-PAD) does'nt make sense, this is documented elsewhere and is not relevant here.