Switch branches/tags
Nothing to show
Find file History
Failed to load latest commit information.
audio Add sample DTMF tones May 27, 2011
test C: fix bug when installing onto an empty release Jan 1, 2015
.gitignore C: Add 'raw_xml' command, useful for debugging Mar 7, 2017
Build_all.vcxproj C: Add a makefile-based build project for Visual Studio Jun 12, 2014
Corelatus-GTH-example-code.sln C: Simplify build in MS Visual Studio Jun 10, 2014
Makefile C: Add 'raw_xml' command, useful for debugging Mar 7, 2017
NMakefile C: Add "job_query" example which queries job counters Aug 10, 2016
README.unix C: Add 'raw_xml' command, useful for debugging Mar 7, 2017
connect_timeslots.c Teach C sample code to display version information Dec 12, 2013
disable.c C: set exit value to nonzero on failure Jun 12, 2014
duplex_lapd.c C: compile with more warnings enabled Jan 1, 2015
enable.c C: set exit value to nonzero on failure Jun 12, 2014
gth_apilib.c C: Add support for 48 kbit/s MTP-2 (Japan) and 56 kbit/s (USA) Oct 9, 2017
gth_apilib.h C: Add support for 48 kbit/s MTP-2 (Japan) and 56 kbit/s (USA) Oct 9, 2017
gth_client_xml_parse.c C: Add 'raw_xml' command, useful for debugging Mar 7, 2017
gth_client_xml_parse.h C: Add 'raw_xml' command, useful for debugging Mar 7, 2017
gth_win32_compat.h C: Fix build for Win32; now tested on Visual Studio 2015 Aug 22, 2016
install_release.c Migrate all http://corelatus links to https Aug 31, 2016
install_start_script.c C: eliminate possible null dereferences following malloc() Jun 5, 2014
job_query.c C: Add "job_query" example which queries job counters Aug 10, 2016
map.c C: improve error message on failure Jun 12, 2014
monitor_dtmf.c C: Make L1 setup optional Jun 12, 2014
playback_file.c C: fix formatting on the 'usage' message Oct 20, 2015
query_set.c C: Teach 'query_resource' to read the schedule Aug 10, 2016
raw_xml.c C: Add 'raw_xml' command, useful for debugging Mar 7, 2017
record.c C: Add option to skip L1 setup in 'record' Aug 12, 2015
save_to_pcap.c C: Add support for 48 kbit/s MTP-2 (Japan) and 56 kbit/s (USA) Oct 9, 2017
unmap.c C: set exit value to nonzero on failure Jun 12, 2014


Author: matthias@corelatus.se

This is example code in C for a Corelatus GTH. It is available under
a BSD licence. It includes:

  A complete parser for the XML a GTH emits. (see gth_client_xml_parse.h)

  A C API for some, but not all, GTH features. (see gth_apilib.h)

  Examples which use the C API:
    - an SS7 sniffer
    - a DTMF sniffer
    - a timeslot recorder
    - a timeslot playback program
    - query and set attributes on GTH resources
    - install software images on a GTH
    - enable duplex (active) ISDN LAPD on a timeslot
    - switch timeslots from one E1 to another
    - enable and disable E1/T1 and SDH/SONET links (layer 1)
    - map and unmap E1/T1 links carried on SDH/SONET

As a convenience for windows users, the distribution at
www.corelatus.com/gth/api/gth_c_examples.zip includes pre-built .exe files.

How to build this code

  * If you're using a unix-like operating system with a GCC toolchain,
    you should just be able to type 'make'. We tested with gcc 4.4.4 on linux.

  * If you're using Microsoft Windows and Visual Studio, there's a
    ready VC Solution. This works out of the box for us (most recently
    tested on VS Express 2015).

  It's also possible to cross-compile from a Linux build system to a
  win32 target. That's not documented, though.

  If you get stuck building this code, feel free to mail matthias@corelatus.se

SS7 sniffer which saves to PCAP (wireshark) format files

  Sniffs SS7 packets from a live E1 link and saves them
  to a 'pcap' file.

  Assumes you have a GTH connected to an SS7 link and a server
  connected to the GTH via IP (ethernet).

  Typical use:

    >./save_to_pcap 1A 2A 16 ss7.pcap
    capturing packets, press ^C to abort
    saving capture to file ss7.pcap.1

  you can then open the ss7.pcap.1 file in 'wireshark' (www.wireshark.org)

  If you don't have a live E1 link, you can use a GTH to replay
  previously recorded data, using 'playback_file'

  There's a WWW page which discusses this at


  On Unix-like systems, output can be piped directly to wireshark or
  tshark for live capture, like this:

    > ./save_to_pcap 1A 2A 16 - | wireshark -k -i -

  On Windows systems, use 'named pipes' to do the same thing:

    > start save_to_pcap 1A 2A 16 \\.\pipe\isup.1
    > wireshark -k -i \\.\pipe\isup.1

DTMF sniffer

  Shows DTMF digits as they're seen on the timeslot. This is also a good
  example to look at to see how to handle asynchronous API messages.

  Typical use, assuming a loopback cable connects P1 and P2:

  > ./monitor_dtmf 1A 5
  event:   l1 message name=pcm2A state=OK
  event:   sync message state=locked
  detected DTMF digit 1 (duration: 94 ms)
  detected DTMF digit 2 (duration: 81 ms)
  detected DTMF digit 3 (duration: 81 ms)

  And in another window:

  > ./playback_file 2A 5 audio/dtmf3

  (if you make your own sequences of DTMF digits, keep in mind that
  you need to put some silence between the digits)

Timeslot recorder

  Record the (bit exact) contents of a timeslot to a file, optionally
  with a .wav header. Typical use:

   >./record 1A 1 recorded_file.wav

Timeslot playback

  Plays back a previously recorded (or generated by some other means,
  for instance converting an audio file to a-law) timeslot on an
  E1. Typical use:

   >./playback_file 1A 1 audio/mfc_fwd_3
   wrote 800 octets to the <player>
   all done

Software image installer

  The software on the GTH can be upgraded with new releases
  (typically with new features and bug fixes) from www.corelatus.com.

  The upgrade process works via the API. Typical use:

   >./install_release /tmp/gth2_system_33c.gth
   Current system image version: gth2_system_32a
   Current failsafe image version: gth2_failsafe_9
   switching to failsafe
   waiting for the GTH to reboot
   GTH back up
   installing software image /tmp/gth2_system_33c.gth
   switching to system
   waiting for the GTH to reboot
   GTH back up
   Current system image version: gth2_system_33c

Query and set attributes on GTH resources

   The GTH has many counters and indicators, called
   "attributes". These attributes are grouped into "resources". The
   attributes can be queried, for example:

   Find out the temperature (and more) on the GTH module:

      >./query_set board
      ROM ID=0x26d02d81000000e7
      power consumption=7.4
      power source=A

   See a list of all the resources:

      >./query_set inventory

   Some attributes can also be changed, for instance to enable
   an E1/T1 interface with default parameters:

      >./query_set pcm1A status enabled

   The GTH API manual, https://www.corelatus.com/gth/api/ has a
   section explaining what all the attributes are for.

Query and set attributes on GTH jobs

   Many of the jobs on the GTH have counters and indicators.
   These can be queried. Here's an example:

      >./job_query m2mo1
      current state=in service
      current load=4
      average load=3
      maximum load=9
      n_no signal units=0
      n_out of service=0
      n_in service=0
      n_proc outage=0
      t_no signal units=22792
      t_out of service=0
      t_in service=23668
      t_proc outage=0

Start duplex LAPD on a timeslot

   Start duplex LAPD signalling on a timeslot. This example
   program has hooks for inserting code to handle Q.931, i.e.
   set up calls.

   Typical use:

     >./duplex_lapd 1A 16

Switch a timeslot from one E1 to another

   Switch one or more timeslots from one E1 to another. This
   turns the GTH into a bare-bones MUX/DXC/Groomer.

   Typical use:

     >./query_set pcm1A status enabled
     >./query_set pcm2A status enabled
     >./connect_timeslots 1A 16 2A 16
     press ^C to shut down all timeslot connections

   The timeslot connections are automatically removed when
   the last program is terminated (e.g. by pressing ^C).

Enable SDH/SONET and E1/T1 links

   Typical use on SDH/SONET hardware:

     >./enable sdh1
     >./enable sdh1 AU 4  TU 12
     >./enable sdh1 SONET true  OC 3  VT 2

   Typical use on E1/T1 hardware:

     >./enable pcm1A
     >./enable pcm2A  framing multiframe
     >./enable pcm2A  framing multiframe  monitoring true

Map an E1/T1 carried on SDH/SONET

   This example is only used on hardware with SDH/SONET interfaces.

   Typical use:

     >./map sdh1:hop1_1:lop1_5_3

   The program replies with the name of the newly mapped E1/T1, in
   this example 'pcm27'. That name can then be used in an 'enable'
   command to start L1 processing on 'pcm27'.

Send raw XML commands

  For debugging, you can send any XML command as per the API manual


  ./raw_xml "<query verbose='true'><job id='ldmo137'/></query>"

GTH API for C programs

  gth_apilib.h provides an interface to the GTH for C programs.  This
  interface lets you set up communication to the GTH and then send
  commands to do everything which the above example programs do, and more.

  gth_apilib.h is not feature complete, i.e. not all GTH features are
  implemented. Extending gth_apilib.h to cover more GTH features is
  left as an exercise, either for the reader or, on request, by

  Typical use:

    #include "gth_apilib.h"

    GTH_api api;
    char buffer[MAX_JOB_ID];

    gth_connect(&api, "");
    gth_new_player(&api, "3A", 16, buffer);


Parser for GTH XML

  gth_client_xml_parse.h provides a C interface to a parser which
  understands all possible responses from a GTH.

  Normally, controlling the GTH through gth_apilib.h is preferable to
  using the parser directly.

Questions, comments? Send mail to Matt Lang (matthias@corelatus.se)