FreeCalypso > hg > themwi-system-sw

annotate README @ 118:a4450ae8fd09

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
sip-manual-out UAC: use the new CSeq parsing function
author Mychaela Falconia <falcon@freecalypso.org>
date Thu, 29 Sep 2022 13:03:27 -0800
parents 97317ede320a
children b7cd66acb123
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
29
dffcae9bc8a3 add README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 This Hg repository contains a work-in-progress named Themyscira Wireless system
dffcae9bc8a3 add README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 software. Themyscira Wireless (ThemWi) is an experimental GSM network operated
dffcae9bc8a3 add README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3 by Mother Mychaela of FreeCalypso at a semi-urban/semi-rural location in
dffcae9bc8a3 add README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 Southern California, USA; this GSM network is operated with Osmocom CNI software
dffcae9bc8a3 add README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 components, all running on a single Slackware Linux server. ThemWi system sw
88
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
6 is a suite of daemon processes and command line tools that run on the same
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
7 machine as all those Osmocom sw components and provide some additional
29
dffcae9bc8a3 add README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 functionality that is not provided "out of the box" by Osmocom, most important
dffcae9bc8a3 add README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 of which is outside connectivity to USA PSTN.
dffcae9bc8a3 add README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10
dffcae9bc8a3 add README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 We are currently experimenting with using bulkvs.com as our USA PSTN
dffcae9bc8a3 add README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 connectivity provider. Like most low-cost PSTN connectivity providers, they
dffcae9bc8a3 add README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 provide the interface to PSTN in the form of a SIP trunk - while I would
dffcae9bc8a3 add README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 absolutely love to get a traditional TDM trunk instead, with SS7 signaling,
dffcae9bc8a3 add README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 such a toy would be far beyond my budget, hence I have to settle for SIP.
dffcae9bc8a3 add README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 Our current status is:
dffcae9bc8a3 add README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17
dffcae9bc8a3 add README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 * We have already obtained a block of USA phone numbers (NANP, chosen numbers
88
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
19 from an exchange area local to us) from BulkVS.
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
20
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
21 * These BulkVS-sourced real NANP numbers have been entered as MSISDNs into
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
22 OsmoHLR records for our test SIMs operating on ThemWi GSM.
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
23
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
24 * We can successfully dial calls from one ThemWi GSM phone to another, with our
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
25 themwi-mncc switch understanding all dialing formats that are considered
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
26 standard for cellular phone networks in USA (full international, or 11 digits
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
27 starting with '1' but no '+', or 10 digits only), as well as our own non-
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
28 standard shorthand dialing method with only 4 digits.
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
29
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
30 * Whenever someone dials one of our NANP numbers from the outside world, BulkVS
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
31 servers send UDP SIP INVITE packets to our server. Our inbound call gateway
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
32 process is themwi-sip-in; this daemon process listens on UDP port 5060,
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
33 accepts SIP calls from BulkVS (ultimately coming from global worldwide PSTN)
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
34 and turns them into GSM MT calls in MNCC format, going through themwi-mncc
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
35 and ultimately to OsmoMSC.
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
36
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
37 The following functionality remains to be implemented:
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
38
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
39 * As a counterpart to themwi-sip-in, there will be another process named
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
40 themwi-sip-out that will serve as a gateway for outbound calls, going from
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
41 GSM MO MNCC to outside PSTN via SIP. The outbound SIP call functional part
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
42 is already implemented in test prototype form in sip-manual-out.
29
dffcae9bc8a3 add README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43
88
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
44 * themwi-mgw will be our transcoding RTP bridge, speaking GSM codecs (FR and
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
45 EFR are currently of most interest) on the side toward Osmocom components and
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
46 G.711 (PCMU or PCMA) on the PSTN side. Right now themwi-mgw is a working
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
47 skeleton that allocates endpoints with RTP & RTCP UDP port pairs, but doesn't
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
48 pass any traffic yet.
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
49
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
50 Differences from osmo-sip-connector
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
51 -----------------------------------
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
52
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
53 In the Osmocom community, the "standard" (or generally accepted) way to connect
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
54 a GSM voice network to the outside world is via osmo-sip-connector, an Osmocom
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
55 process that connects to OsmoMSC's MNCC socket on one end and talks SIP on the
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
56 other end. Our combination of themwi-mncc, themwi-sip-in and themwi-sip-out
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
57 effectively takes the place of osmo-sip-connector. Here are the principal ways
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
58 in which our solution differs from osmo-sip-connector:
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
59
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
60 * o-s-c is designed to connect to a local instance of a SIP PBX such as Asterisk
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
61 or FreeSWITCH, as opposed to interfacing directly to an outside SIP trunk
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
62 from/to a PSTN-via-SIP connectivity provider. themwi-system-sw is different
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
63 in this regard: we do NOT use Asterisk or FreeSWITCH or any other similar
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
64 software of "spaceship" complexity, instead our themwi-sip-in and
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
65 themwi-sip-out processes interface directly to our PSTN-via-SIP connectivity
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
66 provider.
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
67
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
68 * o-s-c has no internal call switching function for calls from one local GSM
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
69 phone to another, instead such switching is punted to the required Asterisk
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
70 or FreeSWITCH etc. With o-s-c, the calling phone's MO call is converted to
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
71 SIP, then Asterisk or other PBX hairpins it back to o-s-c, and then o-s-c
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
72 handles the destination call leg as a separate conversion from SIP back to
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
73 GSM MNCC. In our solution such local calls are switched internally inside
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
74 themwi-mncc, staying native within GSM MNCC land and never turning into SIP.
29
dffcae9bc8a3 add README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75
88
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
76 * o-s-c is based on Sofia-SIP, which in turn uses glib - a very unpleasant
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
77 dependency in this Mother's opinion. In contrast, our implementation of SIP
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
78 is 100% from scratch, written in plain C in the traditional Falconian coding
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
79 style.
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
80
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
81 The need for RTP voice transcoding
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
82 ----------------------------------
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
83
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
84 In the context of GSM voice codecs, the term "transcoding" is used in two
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
85 significantly different meanings:
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
86
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
87 * Transcoding from one lossy GSM codec to another effectively constitutes two
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
88 lossy speech codecs running in tandem, and is a highly undesirable condition.
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
89
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
90 * Running a single GSM codec (not two in tandem), decoding from GSM to G.711 in
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
91 one direction and encoding from G.711 in the other direction, is a standard
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
92 required function for traditional voice gateways between GSM and PSTN.
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
93
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
94 In themwi-system-sw, we need to do transcoding in the second sense above.
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
95 BulkVS SIP call interface to PSTN does not support any of GSM codecs, they only
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
96 support G.711 and G.729, and the same situation is expected to hold with other
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
97 PSTN-via-SIP connectivity providers. We certainly don't want to use G.729 - we
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
98 don't want to run two lossy speech codecs in tandem, first GSM and then G.729 -
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
99 hence the only codecs we speak on the PSTN-via-SIP side of our gateway are PCMU
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
100 and PCMA. Therefore, we need to perform RTP transcoding in our themwi-mgw,
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
101 very similar to a traditional GSM TRAU.
29
dffcae9bc8a3 add README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102
88
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
103 On the GSM side, the two codecs of most interest to us at the present time are
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
104 the original FR and EFR - hence they will be the first to be supported. Note
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
105 the big difference from other Osmocom-using GSM community networks which
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
106 typically prefer or even strictly require AMR instead! Our reasons for focusing
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
107 on FR and EFR instead of AMR are:
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
108
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
109 * Our OsmoBSC time slot configuration is full rate channels only, no half rate
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
110 channels. HR channels are needed only for greater capacity of simultaneous
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
111 calls, but with the total number of people *on the planet* who actively want
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
112 GSM/2G as opposed to LTE or 5G being no more than maybe 10, the thought of
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
113 exceeding the limit of 6 simultaneous call legs per cell (meaning 6 separate
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
114 GSM phone handsets talking *at the same time*) is preposterous.
29
dffcae9bc8a3 add README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
115
88
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
116 * Without any HR channels in OsmoBSC config, AMR means AMR-FR specifically, not
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
117 AMR-HR. The highest level of AMR-FR is identical with EFR - thus if we
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
118 support EFR, do we really need AMR?
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
119
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
120 * The whole point of Themyscira Wireless is to provide service to *vintage*
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
121 mobile phones. Our current collection of vintage phones includes models that
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
122 only support FR1 and EFR (Ericsson I888, Nokia 5190) and Calypso C05 which
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
123 supports FR1, EFR and HR1, but not AMR.
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
124
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
125 * EFR is desirable because it gives better voice quality than FR1, but we must
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
126 support FR1 too, so we can serve the very oldest of phones which support only
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
127 FR1 and nothing else.
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
128
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
129 Voice codec restriction (forcing GSM phones to use EFR instead of AMR, or
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
130 forcing all the way down to FR1) is done in OsmoBSC config, with codec-list
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
131 setting under 'msc 0'.