Recently there’s been some really fun projects to resurrect telecom protocols and standards that are (rightfully) almost dead – like 1xBTS.

I’ve always had a soft spot for ISUP / MTP3, so spent a fun weekend implementing it in FreeSWITCH using Osmocom’s great Sigtran stack and the slop machine.

FreeSWITCH kinda briefly had TDM based SS7 support but it never made it into mainline, it was bolted on the side, and that was 20+ years ago.

ISUP – the ISDN User Part (ISDN being Integrated Services Digital Network) was (and still is in some places) the backbone of the public switched telephone network, and ISUP is old – the “Yellow Book” came out in 1980, so we’re almost half a century old.

I’ve written about basic ISUP call flows before, if you’ve ever worked with H.232, ISUP will seem like it’s cousin, if you’re familiar with SIP, ISUP is more like a strange uncle.

This is real out of band signaling – In old school phone networks, you’d have initially pulse/decadic dialing, where the pulses on the line indicated to the switch the number you wanted to be connected to – this is in band signaling – The same medium that carriers your call is the same medium that carries your signaling. As DTMF / touch tone service was introduced, we got more in-band signaling – The DTMF tones were carried along the speech path, same as your voice (or MFC signaling between switches).

The Captain Crunch 2600Hz phreaking references you might have heard about, relate to again, in band signaling, a switch played a tone to “free” the line so the other side new the line was free, again, in-band signaling in this case getting exploited.

But ISUP is Channel Associated Signaling (CAS) which means the signaling is out of band – a different medium is used to carry the metadata about the call (Called party, calling party, etc) compared to the actual call itself.

Generally this means you’ve got a bank of channels of some description – These could be timeslots on an E1 carrier or they could be POTS lines just carrying voice over -48vDC (Without any DTMF or ringing support).

These channels are “circuits” and each is identified by a Circuit Identification Code (aka CICs) which are the physical carrier resources for the call. They could be time slots on a E/T carrier system, POTS lines, time slots on satellite or submarine cable systems or pigeons – the underlying transport of the call audio (or data or fax or whatever) is not really in the purview of ISUP, rather it manages and sets up the session and allocates the CICs for the call, but doesn’t actually care what goes in them much like SIP and RTP.

Each switch speaking ISUP has a mapping of all of the CICs available to it, and it matches on both ends, so when Switch A says “I’m putting a call on CIC 123” Switch B knows that CIC 123 is actually timeslot 7 on the 5th E1 carrier – or whatever the agreed mapping is.

In ISDN land, on a PRI / BRI circuit these are pretty simple – For a Primary Rate Interface you’ve got 32 timeslots, one is clock, one carries your ISUP signaling (generally timeslot 16) and the other timeslots are free to carry voice channels.

In telephone exchanges these are often tie lines or “links” being chonky 100 pair or larger cables between exchanges, for the purpose of transporting calls from one exchange to another. These are the POTS lines without signaling I mentioned earlier (no AC ring voltage, no dial tone, no onhook / off hook state) – I’ve got a Cisco VG224 I intend to setup for this purpose at some point).

What this means is there’s two parts of making this all work in FreeSWITCH, the first part is getting the signaling (the actual ISUP links) over M3UA up and running.

I’ve tested this on OmniSTP, Cisco ITP and with OsmoSTP (it’s using the Osmocom M3UA / SIGTRAN stack after all).

The second part is getting the CICs up – For this I’m using OsmoMGW to allocate the circuits for us.

Building

This is an out-of-tree FreeSWITCH module you can just bring in at build time.

Add it to your FreeSWITCH source directory:

git submodule add https://github.com/nickvsnetworking/freeswitch-mod_isup.git \
    src/mod/endpoints/mod_isup

Then register it with the build:

• add src/mod/endpoints/mod_isup/Makefile to the AC_CONFIG_FILES list in configure.ac, alongside a pkg-config check for the transport library:PKG_CHECK_MODULES([LIBOSMO_SIGTRAN], [libosmo-sigtran], [have_osmo_sigtran=yes], [have_osmo_sigtran=no]) AM_CONDITIONAL([HAVE_OSMO_SIGTRAN], [test “x$have_osmo_sigtran” = xyes])
• add endpoints/mod_isup to modules.conf.

Then re-run ./bootstrap.sh && ./configure && make. The bundled Makefile.am links the module against libosmo-sigtran and the built libfreeswitch.

Boom, now you’ve got it compiled, you’ll just need to configure it and let the 1970s ring!

The config is done in two places, the Osmocom config and the XML config for mod_isup.

Osmcom Config

Beacuse we’re using Osmocom’s M3UA stack, we configure that in Osmocom config formats, here’s an example M3UA peer:

log stderr
 logging level set-all info
line vty
 no login
cs7 instance 0
 network-indicator national
 point-code 0.0.1
 asp asp-a 2905 0 m3ua
  remote-ip 172.30.0.10
  role asp
  sctp-role client
 as as-a m3ua
  asp asp-a
  routing-key 1 0.0.1
 route-table system
  update route 0.0.0 0.0.0 linkset as-a

OsmoSTP and friends have the docs on how to set this up.

Next we’ll need to configure the ISUP layer that rides on the M3UA, for that we point it at the Osmocom config we just made, and call it from our isup-conf.xml file:

<configuration name="isup.conf" description="ISUP-over-M3UA MGCF">

  <!-- Shared M3UA transport to the STP: one SCTP association / ASP for all
       profiles. asp-name MUST match the 'asp' name in the cs7 config. -->
  <settings>
    <param name="asp-name" value="asp-clnt-stp"/>
    <param name="cs7-config" value="/usr/local/freeswitch/conf/isup-cs7.cfg"/>
    <param name="sccp-ssn" value="0"/>
  </settings>

  <!-- One or more ISUP trunk profiles over that shared transport. Each profile
       has its own point codes, CIC numbering, and MGW, and is dialled as
       isup/<profile-name>/<number>. Inbound messages are demuxed to the profile
       whose OPC is the message's destination point code. -->
  <profiles>
    <profile name="trunk-a">
      <param name="opc" value="607"/>
      <param name="peer-dpc" value="608"/>
      <param name="network-indicator" value="2"/>
      <param name="mgw" value="10.179.1.201:2427"/>
      <param name="cic-min" value="1"/>
      <param name="cic-max" value="4"/>
      <param name="context" value="default"/>
      <param name="dialplan" value="XML"/>
      <param name="auto-answer" value="false"/>
    </profile>

    <!-- A second, independent trunk (own point codes, CICs, MGW):
    <profile name="trunk-b">
      <param name="opc" value="609"/>
      <param name="peer-dpc" value="610"/>
      <param name="network-indicator" value="2"/>
      <param name="mgw" value="10.179.1.202:2427"/>
      <param name="cic-min" value="1"/>
      <param name="cic-max" value="8"/>
      <param name="context" value="default"/>
      <param name="dialplan" value="XML"/>
    </profile>
    -->
  </profiles>

</configuration>

Because ISUP has no media carrying capability, we’re using OsmoMGW to carry the media (CICs).

Then it’s just a matter of restarting FreeSWITCH, all going well you should see the M3UA ASP go up.

There’s a bunch of fs_cli commands to monitor / observe state and run OAM tasks for your busy central office.

Routing calls with ISUP is just like with Sofia, but instead of sofia/internal/[email protected] for example for a SIP call, we call: isup/<profile>/<number> – We support the arguments like CLI on top of this in the form of channel variables.

I’m very keen to actually use this to interface with a real bare-metal TDM speaking device and ideally use the IcE1usb to interface with something period specific, but right now I don’t think I can get away with bringing home a TDM telephone switch to take up a full room of my house. In the meantime I can simulate one right here!

If anyone end up building anything with this, I’d love to hear about it!