Switch branches/tags
Nothing to show
Find file History
Permalink
..
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

README.unix

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 172.16.1.10 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

     https://www.corelatus.com/gth/api/save_to_pcap/index.html

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

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

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

    > start save_to_pcap 172.16.1.10 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 172.16.1.10 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 172.16.1.10 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 172.16.2.7 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 172.16.2.7 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 172.16.1.10 /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 172.16.2.7 board
      architecture=gth2.1
      ROM ID=0x26d02d81000000e7
      temperature=33.4
      power consumption=7.4
      power source=A

   See a list of all the resources:

      >./query_set 172.16.1.10 inventory
      sync
      performance
      cpu
      board
      os
      system_image
      failsafe_image
      http_server
      eth1
      eth2
      pcm1A
      pcm1B
      pcm1C
      ...

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

      >./query_set 172.16.1.10 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 172.16.2.8 m2mo1
      span=1A
      timeslot=1
      n_fisu=34670
      fisu_o=173350
      n_lssu=0
      lssu_o=0
      n_msu=571
      msu_o=38273
      n_esu=0
      esu_o=0
      n_rsu=0
      rsu_o=0
      fib_inv=0
      bib_inv=0
      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
      n_congestion=0
      t_no signal units=22792
      t_out of service=0
      t_in service=23668
      t_proc outage=0
      t_congestion=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 172.16.1.10 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 172.16.1.10 pcm1A status enabled
     >./query_set 172.16.1.10 pcm2A status enabled
     >./connect_timeslots 172.16.1.10 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 172.16.1.10 sdh1
     >./enable 172.16.1.10 sdh1 AU 4  TU 12
     >./enable 172.16.1.10 sdh1 SONET true  OC 3  VT 2

   Typical use on E1/T1 hardware:

     >./enable 172.16.1.10 pcm1A
     >./enable 172.16.1.10 pcm2A  framing multiframe
     >./enable 172.16.1.10 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 172.16.1.10 sdh1:hop1_1:lop1_5_3
     pcm27

   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
  (www.corelatus.se/gth/gth_api.pdf)

  Example:

  ./raw_xml 172.16.1.10 "<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
  Corelatus.

  Typical use:

    #include "gth_apilib.h"

    GTH_api api;
    char buffer[MAX_JOB_ID];

    gth_connect(&api, "172.16.1.10");
    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)