# HG changeset patch # User Mychaela Falconia # Date 1699928457 28800 # Node ID d6630a2d6e807ad39f5852971c96dd4770407eac # Parent 81958b35f74db8628b1abe95113f52c421f96499 doc: beginning of numbering plan documentation diff -r 81958b35f74d -r d6630a2d6e80 doc/NANP-specifics --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/NANP-specifics Mon Nov 13 18:20:57 2023 -0800 @@ -0,0 +1,165 @@ +North American Numbering Plan (NANP) specifics in ThemWi system sw +================================================================== + +Themyscira Wireless system software, as currently written, is strongly tied to +NANP. More precisely, it thoroughly assumes that all local phone numbers are +in +1 country code and follow NANP rules, and that all E.164 telephone numbers +in country codes other than +1 are foreign - numbers which we can call and +receive calls from, but which can never be local to us. + +Why does our software need to have these assumptions baked into it, why can't +it be country-agnostic? The present article answers this question, and this +long answer needs to be thoroughly understood before there can be any meaningful +discussion of how the software could possibly be adapted to other countries and +their respective telephone numbering plans. + +In principle, there exists a standardized dialing format on all GSM phones that +remains the same no matter which country you happen to be in. If you always +enter phone numbers (dialing, SMS manual entry, phone book entries) in full +international format beginning with the '+' symbol (press and hold the '0' +button before the number in most phone UIs), the phone handset firmware will +capture the number with TON=1, NPI=1 attributes (signifying international number +format in GSM call control and SMS protocols) and transmit it as such to the +GSM network. Every properly designed GSM network, upon seeing a number with +these TON=1, NPI=1 attributes, must address the call or message to the country +indicated by the country code at the beginning of the full E.164 number, whether +that country is your local one or some other. Thus if everyone were to always +use only full E.164 numbers in full international format, network software could +hypothetically be written in a country-agnostic way, treating full E.164 phone +numbers as opaque strings without parsing. However, there are two practical +problems with such country-agnostic approach: + +1) Most human users of mobile phones dial local phone numbers (within their own + country) in a way that follows local dialing conventions, rather than in + international format beginning with '+' and their own country code. For + example, in USA a given 10-digit NANP phone number can be dialed as just the + 10 digits NPANXXXXXX, as 11-digit 1NPANXXXXXX, or as full international + +1NPANXXXXXX - and a proper cellphone network MUST accept all 3 formats as + equivalent. + +2) As explained further in this article, a network implementation must be able + to look at a telephone number and immediately tell if that number is locally + owned ("one of ours") or belongs somewhere outside of the local GSM network. + Practical implementation of this distinction requires a database of locally + owned phone numbers, and the implementation of that database in turn becomes + much easier when the local numbering plan is known and fixed. + +Supported dialing formats in ThemWi +=================================== + +When themwi-mncc processes a mobile-originated (MO) call from a GSM subscriber, +it supports dialing the following classes of numbers: + +* NANP numbers in any of the 3 standard dialing formats; + +* International numbers in any country - an international number beginning + with +1 is enforced to be valid NANP, but E.164 numbers in all other country + codes are accepted as-is; + +* Local 4-digit numbers described in (to-be-written) Local-short-numbers + article; + +* Whatever special numbers are configured in themwi-sip-out, such as 511 and + 911. + +Only NANP numbers and specially configured 4-digit numbers (see +Local-short-numbers) can be local - all E.164 numbers in non-NANP country codes +are sent to the outbound call gateway, and all other unrecognized number formats +are likewise sent to themwi-sip-out so that the latter process can catch and map +special numbers like 511, 911 etc. + +If a dialed number is recognized as NANP, themwi-mncc looks in the database of +locally owned numbers to see if the dialed number is one of ours - and the +outcome of this look-up determines if the call is handled locally or sent to +the outside world via themwi-sip-out. + +No 7-digit dialing support +========================== + +In the olden days of land lines, most localities in USA supported 7-digit +dialing: to call Jenny, you would merely dial her local 7-digit number 867-5309, +without needing to dial the local area code; full 10-digit numbers (or 11 digits +with leading '1') had to be dialed only when calling someone in a different +area code from your own. However, this 7-digit dialing has now been disabled +even for land lines in most localities, including the locality where ThemWi +currently operates: per official rules, 7-digit dialing gets disabled (full +10-digit numbers become mandatory) whenever an area code overlay is implemented, +such as overlay of 760 and 442 area codes in our locality. + +In the case of mobile phones, 7-digit dialing never made much sense to begin +with: if you dial only 7 digits, should the implicit area code be taken from +your own number, or should it be the area code of the locality you happen to be +traveling through at the moment? The latter option is impossible in the case +of localities with two or more overlaid NPA codes, and it appears that official +rules once again call for simply disabling 7-digit dialing. + +Based on these considerations, ThemWi system sw was written from the outset to +not support 7-digit dialing - it is no longer relevant in the current state of +telecom culture in USA. We do, however. provide optional support for +abbreviated 4-digit local numbers - see (to-be-written) Local-short-numbers +article. + +Database of locally owned numbers +================================= + +The telecom culture in USA features full number portability - end users can take +their phone numbers with them anywhere, from one telecom provider to another, +and with mobile phones and VoIP services, from one geographic locality to any +other, making the entire country effectively "flat" for local/non-local +distinction purposes. Therefore, the set of phone numbers "owned" (or rented +in reality) by a small network operator such as Themyscira Wireless does not +constitute any kind of clean-cut digit range partition in the numbering plan - +instead we can have a small set of locally owned numbers (say, on the order of +5 to 20 individual numbers), and each of these locally owned numbers can fall +anywhere in the whole nationwide 10-digit numbering plan. So how can we tell, +by looking at an arbitrary NANP number, whether it is "one of ours" or not? + +The implemented solution is an explicitly maintained database of locally owned +phone numbers, described in detail in (to-be-written) Number-database article. +The format of this database (the way numbers are entered, the way the input +format is parsed, and the compiled binary format used for fast look-ups) is +specific to NANP - only NANP numbers can be local in the present design. + +Porting to other national telephone numbering plans +=================================================== + +If someone wishes to port ThemWi system sw for use in other countries with +respective local phone numbers, the following aspects will need to be changed: + +* Based on the structure of your country's national numbering plan, you will + need to come up with an appropriate local number database format for your + country, or if the range of numbers belonging to your GSM network forms a + clean-cut digit range partition, implement that scheme instead. + +* You will need to modify MO call handling to recognize your country code + (rather than +1) as the one calling for parsing and closer scrutiny of the + dialed number, determining if it is local or not. + +* Handling of non-international dialing formats (numbers dialed without '+') + will need to be changed to whatever is appropriate for your country's telecom + culture and customs. + +* Handle all secondary fallout (throughout the code base) from the previous + essential and necessary changes. + +Using fake NANP numbers +======================= + +If someone outside of North America wishes to merely play with ThemWi system sw +on a casual basis, without actually interconnecting to your non-USA PSTN with +non-NANP real phone numbers, the easiest way to bring the software up is to use +fake NANP numbers. There are two types of guaranteed-fake (can't collide with +real ones) phone numbers in NANP: + +1) NPA-555-01XX, where NPA is some real area code for some (any) actual locality + in USA and XX can be any two digits. This number range is specifically set + aside for use in movies etc, with realistic USA settings - the area code can + be any real one, but 555-01XX numbers are reserved for fake use in every + area code. + +2) Fake area codes of form N9X (290-299, 390-399, ..., 990-999) are also good + for guaranteed-fake numbers as the middle digit of NPA is not allowed to be + '9' per official NANP rules. This method allows large ranges of fake NANP + numbers. + +See Fake-NANP-numbers article (to be written) for more info. diff -r 81958b35f74d -r d6630a2d6e80 doc/Use-outside-USA --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/Use-outside-USA Mon Nov 13 18:20:57 2023 -0800 @@ -0,0 +1,48 @@ +Themyscira Wireless system sw was written for deployment in USA, with a key goal +of full interconnection with USA PSTN. However, as the software grows in +functionality and becomes more interesting, there is a growing possibility that +someone some day may be interested in running our sw outside of USA, or outside +of North American continent in general. This document outlines some thoughts +for how it might be possible to adapt the present software for use in other +geopolitical regions. + +The first point that needs to be made clear is that software has no extrasensory +psychic powers - it cannot divine where you are located in physical geography, +and it doesn't care. Instead the aspects which telephony software cares about +are dialing formats and numbering plans - and in the case of Themyscira Wireless +system sw, the "thing" to which our sw is tied is NANP, the telephone numbering +plan of +1 country code. + +If anyone is contemplating the idea of running ThemWi system sw in a country +other than USA, the first question that needs to be answered is: are you looking +to interconnect with your country's national public telephone network similarly +to how we (ThemWi) interconnect with USA PSTN, or are you only interested in +running an isolated (test or toy) network without interconnection to PSTN? + +Interconnecting with PSTN outside of USA +======================================== + +Suppose that your country has SIP trunk providers who operate similarly to those +in USA: you rent a range of numbers in your country's national telephone +numbering plan, calls addressed to those numbers are delivered to your Internet- +connected server via SIP, and you can likewise use SIP to dial outbound calls. +At this point our current software will NOT work as-is - it will require +modifications to work with the local numbering plan being some other than NANP. + +Please read our NANP-specifics article for the explanation of why our current +software is tied to NANP, and in exactly what ways. That article also gives an +outline of what changes would need to be made to support other national +telephone numbering plans. + +Running an isolated instance of Osmocom CNI + ThemWi system sw +============================================================== + +If you are not interconnecting with your country's public phone network with +real phone numbers from your country's national telephone numbering plan, then +it doesn't matter where you are located in terms of physical geography - your +network will be either fully isolated (self-contained) or perhaps interconnected +with other hobbyist or community networks - but not with general PSTN. + +If you would like to run ThemWi system sw in such non-PSTN-connected +configuration, the easiest way is to use fake NANP numbers - see +Fake-NANP-numbers article (to be written) for more info.