--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Proto-SMSC-testing	Sun Aug 27 21:47:19 2023 -0800
@@ -0,0 +1,146 @@
+The present code repository contains a proto-SMSC test framework: a pair of
+programs that connect to OsmoHLR in the role of a GSUP-speaking SMSC and allow
+the rest of SMS-over-GSUP path to be exercised and tested.
+
+To exercise SMS flow between an MS and the present proto-SMSC, set up your test
+environment as follows:
+
+0) Locate branch falconia/os6135 in osmo-hlr and osmo-msc git repositories;
+   compile and run osmo-hlr and osmo-msc versions from this branch.
+
+1) Configure OsmoHLR to expect an SMSC at a certain IPA name, and to route
+   MO SMS to this SMSC.  Example config:
+
+hlr
+ reject-cause not-found plmn-not-allowed
+ reject-cause no-proxy net-fail
+ gsup
+  bind ip 127.0.0.1
+  ipa-name Example-HLR
+ ussd route prefix *#100# internal own-msisdn
+ ussd route prefix *#101# internal own-imsi
+ smsc entity Example-SMSC
+ smsc route 19990014444 Example-SMSC
+
+In this example the SMSC is operated at SC-address (fake Global Title)
++19990014444 (a number falling into a reserved/invalid range in the North
+American Numbering Plan), with IPA name Example-SMSC, and you are configuring
+OsmoHLR to map this SC-address to this IPA name.  SM-RP messages addressed to
+any other SMSC will be rejected - a user trying to send something to a
+commercial operator's SMSC will get an error during SMS send attempt, instead
+of her message being sneakily intercepted and diverted to Example-SMSC.
+
+OTOH, if you prefer to operate your network in a guest roaming manner, allowing
+foreign SIMs without an actual roaming interconnection in place, and you wish
+to operate so that all such guest-roaming users will send their MO SMS to your
+SMSC while their phones "think" that they are addressing their native operator's
+SMSC, change the last line to:
+
+ smsc default-route Example-SMSC
+
+2) Ensure that your OsmoMSC configuration includes the following bits:
+
+msc
+ sms-over-gsup
+hlr
+ ipa-name Example-MSC
+
+The sms-over-gsup bit should be obvious, but the need for an explicitly set
+ipa-name is much less so.  The explicitly set ipa-name doesn't matter for MO
+SMS, but it is needed for MT SMS to work.  When an MT-forwardSM.req message
+arrives at the MSC from an SMSC, routed via OsmoHLR, the MSC will need to
+respond to it, and this response needs to reach the MT-sending SMSC.  These
+responses are routed passively by OsmoHLR, and for this passive routing to work,
+the sender of the response message needs to include source_name IE.  Thus
+explicitly set ipa-name for the MSC becomes a requirement, just like with
+inter-MSC handover.
+
+3) Run proto-smsc-daemon like this:
+
+proto-smsc-daemon Example-SMSC mo-sms-log /tmp/sendmt_socket
+
+The first argument is the IPA name this proto-SMSC should give itself (needs to
+match OsmoHLR config), the second argument is the name of a log file that will
+be opened for writing, and the third argument is the pathname to which a local
+UNIX domain socket will be bound.
+
+Any time an MS sends MO SMS to this proto-SMSC, the message will be written
+into the line-oriented log file which you named as the second argument to
+proto-smsc-daemon.  Here is what messages will look like:
+
+2023-08-25T23:53:01Z Rx MO SM
+IMSI: 310xxxxxxxxxxxx
+SM-RP-MR: 0x03
+SM-RP-DA: SMSC TON=1 NPI=1 1xxxxxxxxxx
+SM-RP-OA: MSISDN TON=1 NPI=1 1xxxxxxxxxx
+SM-RP-UI: 13 bytes
+010304814444000004D4F29C0E
+
+('x' characters in the above fragment are [0-9] digits in reality, but the
+ numbers had to be redacted out for privacy, as the test was done on a live
+ network that operates with real NANP phone numbers.)
+
+The string of hex digits that makes up the final line of each recorded message
+is the GSM 03.40 SMS-SUBMIT TPDU that has been received from the MS in the
+SM-RP-UI field.  proto-smsc-daemon writes it out in raw hex, but you can get a
+complete decoding by feeding this log file to sms-pdu-decode utility from
+freecalypso-tools Hg repository.  You will need to run sms-pdu-decode with -n
+option so it will know not to expect a prepended SC-address in front of the TPDU
+(as happens in GSM 07.05), and you will need to compile from "bleeding edge" Hg
+code: the addition of this option has not made it into a release yet.
+
+Running the above log fragment through sms-pdu-decode -np, we get the following
+decoding:
+
+2023-08-25T23:53:01Z Rx MO SM
+IMSI: 310xxxxxxxxxxxx
+SM-RP-MR: 0x03
+SM-RP-DA: SMSC TON=1 NPI=1 1xxxxxxxxxx
+SM-RP-OA: MSISDN TON=1 NPI=1 1xxxxxxxxxx
+SM-RP-UI: 13 bytes
+010304814444000004D4F29C0E
+
+First-Octet: 0x01
+MR: 0x03
+To: 4444 (type 0x81)
+PID: 0x00
+DCS: 0x00 (7-bit)
+Length: 4
+
+Test
+
+4) To test MT SMS, you will need to compile and install this additional sw
+   package (very small):
+
+https://www.freecalypso.org/hg/sms-coding-utils/
+
+To send a test MT SMS, run a shell pipeline like the following:
+
+sms-encode-text 'Message text blah blah' | gen-sms-deliver-pdu 1234 | proto-smsc-sendmt 19990014444 310999-001 /tmp/sendmt_socket
+
+The various bits are:
+
+* The argument to sms-encode-text is the human-level message body to be sent.
+  One can also omit this command line argument and supply the message body on
+  stdin instead.
+
+* The argument to gen-sms-deliver-pdu is the "From" number to be inserted into
+  the SMS-DELIVER TPDU being generated.
+
+* The first argument to proto-smsc-sendmt is the SC-address to be transmitted
+  in SM-RP-OA.  This SMSC address is passed through to the MS, and savvy users
+  of hacker-friendly MS can see it: it is written into SIM SMS storage which
+  can then be read out and decoded, it can be retrieved via GSM 07.05, plus
+  other MS-specific options like /pcm/SMS on Pirelli DP-L10 running that phone's
+  original proprietary fw.
+
+* The second argument to proto-smsc-sendmt is the IMSI to which the message
+  should be sent.  (Key point: MT SMS recipients in SMS-over-GSUP are addressed
+  by IMSI, not by MSISDN!)  proto-smsc-sendmt supports FreeCalypso shorthand
+  notation for IMSI entry: 310999-001 in this example expands into
+  310999000000001.  Of course you can also enter the full IMSI manually, if you
+  don't mind torturing your eyes counting all those zeros.
+
+* The third argument to proto-smsc-sendmt is the local UNIX domain socket to
+  which the composed GSUP message should be sent; it needs to match the socket
+  pathname you gave to proto-smsc-daemon.