The GTH API

All Corelatus hardware is controlled using the same text protocol sent over a TCP socket. Here is an example of how to enable MTP-2 monitoring on a timeslot:

    <new>
       <mtp2_monitor ip_addr='128.250.22.3' ip_port='2453'>
          <pcm_source span='2' timeslot='16'/>
       </mtp2_monitor>
    </new>

The API is just text sent over a TCP socket, so it is programming language and OS neutral. If a system can open a socket, it can control Corelatus hardware. We have used Java, C#, C, C++, Python, Perl, BASH scripts and Erlang to control the GTH, on machines running various unix-like operating systems and various operating systems from Microsoft.

Specification

API Specification (PDF)
DTD for commands
DTD for responses

Example code: C

C isn't the best language for this type of work, but since "everyone" knows how to compile a C program, we've written a set of plain C examples to

  • Sniff an E1, decode SS7 MTP-2 and save the signal units to a file in libpcap (Wireshark) format. (Read more)
  • Record an E1/T1 timeslot-to-file and play it back on a timeslot.
  • Monitor CAS R2 and DTMF signalling
  • Upgrade the firmware on a GTH module
  • Query and set resource attributes (IP address, temperature, L1 counters, etc.) on a GTH
  • Start a duplex ISDN LAPD signalling timeslot.
  • Enable and disable E1/T1 and SDH/SONET links.
  • Map and unmap E1/T1 links carried on SDH/SONET.

These examples are discussed in a blog entry.

gth_c_examples.zip

Example code: erlang

This example includes a feature-complete wrapper, gth.erl, for the GTH API, i.e. all of the GTH's features are available through an erlang interface. Here's how you start MTP-2 monitoring with it:

     41> {ok, A} = gth:start_link("172.16.2.7").
         {ok,<0.188.0>}
     42> {ok, ID, Socket} = gth:new_mtp2_monitor(A, "1A", 16).
         {ok,"m2mo21",#Port<0.2261>}
  

Apart from the wrapper, there's an Erlang implementation of

  • an SS7-to-pcap (wireshark) sniffer (read more)
  • an SS7 sniffer with a simple MTP-3 and ISUP decoder
  • an E1/T1 timeslot record/replay module

gth_erlang_api.zip

Example code: python

The python example code package contains

  • code to enable an E1/T1 interface on a GTH
  • an E1/T1 timeslot-to-file recorder
  • an E1/T1 file-to-timeslot player
  • an SS7 call sniffer with a simple MTP-3 and ISUP decoder

The examples are built on top of a small-ish GTH API wrapper in python, so it's a useful base to build other scripts on.

gth_python_examples.zip

Example code: Perl

The Perl example code package contains the same examples as the Python package (but written in Perl!), along with a partial GTH API wrapper written as a Perl module.

gth_perl_examples.zip

Example code: java XML parser interface

A Java package which includes an interface to the Xerces XML parser. Xerces is included in JDK 1.4 and later. The sample code includes a tool to upgrade the software on the GTH.

XML Tool (source)
XML Tool (precompiled)