FreeCalypso > hg > themwi-system-sw

comparison doc/NANP-specifics @ 268:d6630a2d6e80

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: beginning of numbering plan documentation
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 13 Nov 2023 18:20:57 -0800
parents
children b54fa3e4d81f
comparison
equal deleted inserted replaced
267:81958b35f74d 268:d6630a2d6e80
1 North American Numbering Plan (NANP) specifics in ThemWi system sw
2 ==================================================================
3
4 Themyscira Wireless system software, as currently written, is strongly tied to
5 NANP. More precisely, it thoroughly assumes that all local phone numbers are
6 in +1 country code and follow NANP rules, and that all E.164 telephone numbers
7 in country codes other than +1 are foreign - numbers which we can call and
8 receive calls from, but which can never be local to us.
9
10 Why does our software need to have these assumptions baked into it, why can't
11 it be country-agnostic? The present article answers this question, and this
12 long answer needs to be thoroughly understood before there can be any meaningful
13 discussion of how the software could possibly be adapted to other countries and
14 their respective telephone numbering plans.
15
16 In principle, there exists a standardized dialing format on all GSM phones that
17 remains the same no matter which country you happen to be in. If you always
18 enter phone numbers (dialing, SMS manual entry, phone book entries) in full
19 international format beginning with the '+' symbol (press and hold the '0'
20 button before the number in most phone UIs), the phone handset firmware will
21 capture the number with TON=1, NPI=1 attributes (signifying international number
22 format in GSM call control and SMS protocols) and transmit it as such to the
23 GSM network. Every properly designed GSM network, upon seeing a number with
24 these TON=1, NPI=1 attributes, must address the call or message to the country
25 indicated by the country code at the beginning of the full E.164 number, whether
26 that country is your local one or some other. Thus if everyone were to always
27 use only full E.164 numbers in full international format, network software could
28 hypothetically be written in a country-agnostic way, treating full E.164 phone
29 numbers as opaque strings without parsing. However, there are two practical
30 problems with such country-agnostic approach:
31
32 1) Most human users of mobile phones dial local phone numbers (within their own
33 country) in a way that follows local dialing conventions, rather than in
34 international format beginning with '+' and their own country code. For
35 example, in USA a given 10-digit NANP phone number can be dialed as just the
36 10 digits NPANXXXXXX, as 11-digit 1NPANXXXXXX, or as full international
37 +1NPANXXXXXX - and a proper cellphone network MUST accept all 3 formats as
38 equivalent.
39
40 2) As explained further in this article, a network implementation must be able
41 to look at a telephone number and immediately tell if that number is locally
42 owned ("one of ours") or belongs somewhere outside of the local GSM network.
43 Practical implementation of this distinction requires a database of locally
44 owned phone numbers, and the implementation of that database in turn becomes
45 much easier when the local numbering plan is known and fixed.
46
47 Supported dialing formats in ThemWi
48 ===================================
49
50 When themwi-mncc processes a mobile-originated (MO) call from a GSM subscriber,
51 it supports dialing the following classes of numbers:
52
53 * NANP numbers in any of the 3 standard dialing formats;
54
55 * International numbers in any country - an international number beginning
56 with +1 is enforced to be valid NANP, but E.164 numbers in all other country
57 codes are accepted as-is;
58
59 * Local 4-digit numbers described in (to-be-written) Local-short-numbers
60 article;
61
62 * Whatever special numbers are configured in themwi-sip-out, such as 511 and
63 911.
64
65 Only NANP numbers and specially configured 4-digit numbers (see
66 Local-short-numbers) can be local - all E.164 numbers in non-NANP country codes
67 are sent to the outbound call gateway, and all other unrecognized number formats
68 are likewise sent to themwi-sip-out so that the latter process can catch and map
69 special numbers like 511, 911 etc.
70
71 If a dialed number is recognized as NANP, themwi-mncc looks in the database of
72 locally owned numbers to see if the dialed number is one of ours - and the
73 outcome of this look-up determines if the call is handled locally or sent to
74 the outside world via themwi-sip-out.
75
76 No 7-digit dialing support
77 ==========================
78
79 In the olden days of land lines, most localities in USA supported 7-digit
80 dialing: to call Jenny, you would merely dial her local 7-digit number 867-5309,
81 without needing to dial the local area code; full 10-digit numbers (or 11 digits
82 with leading '1') had to be dialed only when calling someone in a different
83 area code from your own. However, this 7-digit dialing has now been disabled
84 even for land lines in most localities, including the locality where ThemWi
85 currently operates: per official rules, 7-digit dialing gets disabled (full
86 10-digit numbers become mandatory) whenever an area code overlay is implemented,
87 such as overlay of 760 and 442 area codes in our locality.
88
89 In the case of mobile phones, 7-digit dialing never made much sense to begin
90 with: if you dial only 7 digits, should the implicit area code be taken from
91 your own number, or should it be the area code of the locality you happen to be
92 traveling through at the moment? The latter option is impossible in the case
93 of localities with two or more overlaid NPA codes, and it appears that official
94 rules once again call for simply disabling 7-digit dialing.
95
96 Based on these considerations, ThemWi system sw was written from the outset to
97 not support 7-digit dialing - it is no longer relevant in the current state of
98 telecom culture in USA. We do, however. provide optional support for
99 abbreviated 4-digit local numbers - see (to-be-written) Local-short-numbers
100 article.
101
102 Database of locally owned numbers
103 =================================
104
105 The telecom culture in USA features full number portability - end users can take
106 their phone numbers with them anywhere, from one telecom provider to another,
107 and with mobile phones and VoIP services, from one geographic locality to any
108 other, making the entire country effectively "flat" for local/non-local
109 distinction purposes. Therefore, the set of phone numbers "owned" (or rented
110 in reality) by a small network operator such as Themyscira Wireless does not
111 constitute any kind of clean-cut digit range partition in the numbering plan -
112 instead we can have a small set of locally owned numbers (say, on the order of
113 5 to 20 individual numbers), and each of these locally owned numbers can fall
114 anywhere in the whole nationwide 10-digit numbering plan. So how can we tell,
115 by looking at an arbitrary NANP number, whether it is "one of ours" or not?
116
117 The implemented solution is an explicitly maintained database of locally owned
118 phone numbers, described in detail in (to-be-written) Number-database article.
119 The format of this database (the way numbers are entered, the way the input
120 format is parsed, and the compiled binary format used for fast look-ups) is
121 specific to NANP - only NANP numbers can be local in the present design.
122
123 Porting to other national telephone numbering plans
124 ===================================================
125
126 If someone wishes to port ThemWi system sw for use in other countries with
127 respective local phone numbers, the following aspects will need to be changed:
128
129 * Based on the structure of your country's national numbering plan, you will
130 need to come up with an appropriate local number database format for your
131 country, or if the range of numbers belonging to your GSM network forms a
132 clean-cut digit range partition, implement that scheme instead.
133
134 * You will need to modify MO call handling to recognize your country code
135 (rather than +1) as the one calling for parsing and closer scrutiny of the
136 dialed number, determining if it is local or not.
137
138 * Handling of non-international dialing formats (numbers dialed without '+')
139 will need to be changed to whatever is appropriate for your country's telecom
140 culture and customs.
141
142 * Handle all secondary fallout (throughout the code base) from the previous
143 essential and necessary changes.
144
145 Using fake NANP numbers
146 =======================
147
148 If someone outside of North America wishes to merely play with ThemWi system sw
149 on a casual basis, without actually interconnecting to your non-USA PSTN with
150 non-NANP real phone numbers, the easiest way to bring the software up is to use
151 fake NANP numbers. There are two types of guaranteed-fake (can't collide with
152 real ones) phone numbers in NANP:
153
154 1) NPA-555-01XX, where NPA is some real area code for some (any) actual locality
155 in USA and XX can be any two digits. This number range is specifically set
156 aside for use in movies etc, with realistic USA settings - the area code can
157 be any real one, but 555-01XX numbers are reserved for fake use in every
158 area code.
159
160 2) Fake area codes of form N9X (290-299, 390-399, ..., 990-999) are also good
161 for guaranteed-fake numbers as the middle digit of NPA is not allowed to be
162 '9' per official NANP rules. This method allows large ranges of fake NANP
163 numbers.
164
165 See Fake-NANP-numbers article (to be written) for more info.