FreeCalypso > hg > themwi-system-sw

annotate README @ 141:e499e8db8b82

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
sip-in: handle call hold and retrieve
author Mychaela Falconia <falcon@freecalypso.org>
date Sat, 08 Oct 2022 13:28:30 -0800
parents b7cd66acb123
children b259e2722485
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
129
b7cd66acb123 README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 88
diff changeset
37 * These inbound calls per the previous bullet point also include fully working
b7cd66acb123 README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 88
diff changeset
38 voice path, with our themwi-mgw transcoding the two RTP streams (one in each
b7cd66acb123 README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 88
diff changeset
39 direction) between the original GSM 06.10 codec on the GSM side and G.711
b7cd66acb123 README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 88
diff changeset
40 PCMU or PCMA on the PSTN-via-SIP side. This voice call gateway includes
b7cd66acb123 README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 88
diff changeset
41 working DTMF support: START DTMF and STOP DTMF commands from GSM phones pass
b7cd66acb123 README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 88
diff changeset
42 through OsmoMSC, themwi-mncc and themwi-sip-in to themwi-mgw, and the latter
b7cd66acb123 README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 88
diff changeset
43 process injects in-band DTMF tones into the G.711 RTP stream that is otherwise
b7cd66acb123 README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 88
diff changeset
44 generated by transcoding from GSM voice codecs.
b7cd66acb123 README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 88
diff changeset
45
88
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
46 The following functionality remains to be implemented:
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
47
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
48 * 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
49 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
50 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
51 is already implemented in test prototype form in sip-manual-out.
29
dffcae9bc8a3 add README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52
129
b7cd66acb123 README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 88
diff changeset
53 * Right now themwi-mgw supports only the original FR1 codec (GSM 06.10) on the
b7cd66acb123 README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 88
diff changeset
54 GSM side; the Mother's desire is to also support EFR codec as a high priority,
b7cd66acb123 README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 88
diff changeset
55 and maybe some time later AMR as a lower priority.
88
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
56
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
57 Differences from osmo-sip-connector
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
58 -----------------------------------
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 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
61 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
62 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
63 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
64 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
65 in which our solution differs from osmo-sip-connector:
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
66
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
67 * 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
68 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
69 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
70 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
71 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
72 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
73 provider.
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
74
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
75 * 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
76 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
77 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
78 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
79 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
80 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
81 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
82
88
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
83 * 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
84 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
85 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
86 style.
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
87
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
88 The need for RTP voice transcoding
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
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
91 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
92 significantly different meanings:
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 * 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
95 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
96
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
97 * 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
98 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
99 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
100
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
101 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
102 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
103 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
104 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
105 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
106 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
107 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
108 very similar to a traditional GSM TRAU.
29
dffcae9bc8a3 add README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
109
88
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
110 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
111 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
112 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
113 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
114 on FR and EFR instead of AMR are:
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
115
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
116 * 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
117 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
118 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
119 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
120 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
121 GSM phone handsets talking *at the same time*) is preposterous.
29
dffcae9bc8a3 add README
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
122
88
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
123 * 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
124 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
125 support EFR, do we really need AMR?
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
126
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
127 * 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
128 mobile phones. Our current collection of vintage phones includes models that
129
b7cd66acb123 README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 88
diff changeset
129 only support FR1 and EFR (Ericsson I888, Nokia 5190 and 6190), as well as
b7cd66acb123 README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 88
diff changeset
130 Calypso C05 which supports FR1, EFR and HR1, but not AMR.
88
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
131
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
132 * 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
133 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
134 FR1 and nothing else.
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
135
97317ede320a README: update for current status
Mychaela Falconia <falcon@freecalypso.org>
parents: 29
diff changeset
136 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
137 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
138 setting under 'msc 0'.