This Hg repository contains a work-in-progress named Themyscira Wireless system
software.  Themyscira Wireless (ThemWi) is an experimental GSM network operated
by Mother Mychaela of FreeCalypso at a semi-urban/semi-rural location in
Southern California, USA; this GSM network is operated with Osmocom CNI software
components, all running on a single Slackware Linux server.  ThemWi system sw
is a suite of daemon processes and command line tools that run on the same
machine as all those Osmocom sw components and provide some additional
functionality that is not provided "out of the box" by Osmocom, most important
of which is outside connectivity to USA PSTN.

We are currently experimenting with using bulkvs.com as our USA PSTN
connectivity provider.  Like most low-cost PSTN connectivity providers, they
provide the interface to PSTN in the form of a SIP trunk - while I would
absolutely love to get a traditional TDM trunk instead, with SS7 signaling,
such a toy would be far beyond my budget, hence I have to settle for SIP.
Our current status is:

* We have already obtained a block of USA phone numbers (NANP, chosen numbers
  from an exchange area local to us) from BulkVS.

* These BulkVS-sourced real NANP numbers have been entered as MSISDNs into
  OsmoHLR records for our test SIMs operating on ThemWi GSM.

* We can successfully dial calls from one ThemWi GSM phone to another, with our
  themwi-mncc switch understanding all dialing formats that are considered
  standard for cellular phone networks in USA (full international, or 11 digits
  starting with '1' but no '+', or 10 digits only), as well as our own non-
  standard shorthand dialing method with only 4 digits.

* Whenever someone dials one of our NANP numbers from the outside world, BulkVS
  servers send UDP SIP INVITE packets to our server.  Our inbound call gateway
  process is themwi-sip-in; this daemon process listens on UDP port 5060,
  accepts SIP calls from BulkVS (ultimately coming from global worldwide PSTN)
  and turns them into GSM MT calls in MNCC format, going through themwi-mncc
  and ultimately to OsmoMSC.

* Our outbound call gateway is themwi-sip-out, serving as a counterpart to
  themwi-sip-in.  All GSM MO calls are initially handled by themwi-mncc, which
  decides (based on the dialed number) whether to switch the call locally
  (calling another ThemWi GSM phone) or to pass it to themwi-sip-out.  The
  latter process turns outbound calls into SIP and sends them to BulkVS, and we
  are successfully able to call any PSTN destination anywhere in the +1 country
  code.  (themwi-sip-out has provisions for international routes too, but we
  haven't set up any yet.)

* These inbound and outbound calls per the previous two bullet points also
  include fully working voice path, with our themwi-mgw transcoding the two RTP
  streams (one in each direction) between the original GSM 06.10 codec or
  GSM 06.60 EFR codec on the GSM side and G.711 PCMU or PCMA on the PSTN-via-SIP
  side.  This voice call gateway includes working DTMF support: START DTMF and
  STOP DTMF commands from GSM phones pass through OsmoMSC, themwi-mncc and
  themwi-sip-{in,out} to themwi-mgw, and the latter process injects in-band DTMF
  tones into the G.711 RTP stream that is otherwise generated by transcoding
  from GSM voice codecs.

The following functionality remains to be implemented:

* The only GSM codecs currently supported are the original FR (GSM 06.10) and
  EFR (GSM 06.60).  At some point it would be nice to add support for AMR and
  maybe even HR1, purely for demonstration of its poor voice quality.

* The Presiding High Priestess of Themyscira Wireless has a desire to implement
  in-band GSM 08.62 TFO inside our G.711 RTP interface to outside PSTN.  Right
  now if a call is connected between a ThemWi GSM phone on one end and another
  GSM phone on some other network anywhere else in the world, an undesirable
  tandem transcoding takes place: two lossy GSM speech codecs run in tandem,
  one on the ThemWi GSM leg of the call and another on the distant GSM network's
  leg, with a G.711 64 kbps connection in between.  If we implement GSM 08.62
  TFO inside our G.711 RTP interface which we present to the outside world, we
  shall achieve TFO calls at least between ThemWi and any other community GSM
  networks using our software, and maybe even between ThemWi and some legacy
  commercial GSM networks, if any still remain in parts of the world that are
  accessible to us.

* No work whatsoever has been done on SMS as of yet - all of our ThemWi work so
  far has been in support of voice call functionality only.  Adding SMS support
  will require 3 major areas of work:

1) We will need to climb the learning curve and assess the current state of SMS
   support in Osmocom CNI software.

2) We'll have to find a USA PSTN connectivity provider who supports P2P SMS: if
   we are operating a GSM network and providing mobile phone service to human
   end users, any SMS usage in such scenario MUST be classified as P2P rather
   than A2P.  However, gaining access to P2P SMS in USA telecom environment is
   currently very difficult (every major provider forcibly imposes A2P
   misclassification with no option of P2P correct classification), in stark
   contrast to very easy and cheap access to voice PSTN with NANP phone numbers.

3) When and if we find that necessary USA PSTN connectivity provider with P2P
   SMS provision, we will need to implement whatever software will be needed to
   interconnect it with an OsmoCNI GSM network, likely a custom SMSC.

Differences from osmo-sip-connector
-----------------------------------

In the Osmocom community, the "standard" (or generally accepted) way to connect
a GSM voice network to the outside world is via osmo-sip-connector, an Osmocom
process that connects to OsmoMSC's MNCC socket on one end and talks SIP on the
other end.  Our combination of themwi-mncc, themwi-sip-in and themwi-sip-out
effectively takes the place of osmo-sip-connector.  Here are the principal ways
in which our solution differs from osmo-sip-connector:

* o-s-c is designed to connect to a local instance of a SIP PBX such as Asterisk
  or FreeSWITCH, as opposed to interfacing directly to an outside SIP trunk
  from/to a PSTN-via-SIP connectivity provider.  themwi-system-sw is different
  in this regard: we do NOT use Asterisk or FreeSWITCH or any other similar
  software of "spaceship" complexity, instead our themwi-sip-in and
  themwi-sip-out processes interface directly to our PSTN-via-SIP connectivity
  provider.

* o-s-c has no internal call switching function for calls from one local GSM
  phone to another, instead such switching is punted to the required Asterisk
  or FreeSWITCH etc.  With o-s-c, the calling phone's MO call is converted to
  SIP, then Asterisk or other PBX hairpins it back to o-s-c, and then o-s-c
  handles the destination call leg as a separate conversion from SIP back to
  GSM MNCC.  In our solution such local calls are switched internally inside
  themwi-mncc, staying native within GSM MNCC land and never turning into SIP.

* o-s-c is based on Sofia-SIP, which in turn uses glib - a very unpleasant
  dependency in this Mother's opinion.  In contrast, our implementation of SIP
  is 100% from scratch, written in plain C in the traditional Falconian coding
  style.

The need for RTP voice transcoding
----------------------------------

In the context of GSM voice codecs, the term "transcoding" is used in two
significantly different meanings:

* Transcoding from one lossy GSM codec to another effectively constitutes two
  lossy speech codecs running in tandem, and is a highly undesirable condition.

* Running a single GSM codec (not two in tandem), decoding from GSM to G.711 in
  one direction and encoding from G.711 in the other direction, is a standard
  required function for traditional voice gateways between GSM and PSTN.

In themwi-system-sw, we need to do transcoding in the second sense above.
BulkVS SIP call interface to PSTN does not support any of GSM codecs, they only
support G.711 and G.729, and the same situation is expected to hold with other
PSTN-via-SIP connectivity providers.  We certainly don't want to use G.729 - we
don't want to run two lossy speech codecs in tandem, first GSM and then G.729 -
hence the only codecs we speak on the PSTN-via-SIP side of our gateway are PCMU
and PCMA.  Therefore, we need to perform RTP transcoding in our themwi-mgw,
very similar to a traditional GSM TRAU.

On the GSM side, the two codecs of most interest to us at the present time are
the original FR and EFR - hence they will be the first to be supported.  Note
the big difference from other Osmocom-using GSM community networks which
typically prefer or even strictly require AMR instead!  Our reasons for focusing
on FR and EFR instead of AMR are:

* Our OsmoBSC time slot configuration is full rate channels only, no half rate
  channels.  HR channels are needed only for greater capacity of simultaneous
  calls, but with the total number of people *on the planet* who actively want
  GSM/2G as opposed to LTE or 5G being no more than maybe 10, the thought of
  exceeding the limit of 6 simultaneous call legs per cell (meaning 6 separate
  GSM phone handsets talking *at the same time*) is preposterous.

* Without any HR channels in OsmoBSC config, AMR means AMR-FR specifically, not
  AMR-HR.  The highest level of AMR-FR is identical with EFR - thus if we
  support EFR, do we really need AMR?

* The whole point of Themyscira Wireless is to provide service to *vintage*
  mobile phones.  Our current collection of vintage phones includes models that
  only support FR1 and EFR (Ericsson I888, Nokia 5190 and 6190), as well as
  Calypso C05 which supports FR1, EFR and HR1, but not AMR.

* EFR is desirable because it gives better voice quality than FR1, but we must
  support FR1 too, so we can serve the very oldest of phones which support only
  FR1 and nothing else.

Voice codec restriction (forcing GSM phones to use EFR instead of AMR, or
forcing all the way down to FR1) is done in OsmoBSC config, with codec-list
setting under 'msc 0'.