move smpp.adoc to common chapters, generalize

OsmoMSC will need the same SMPP chapter as OsmoNITB.

In smpp.adoc, replace program name with parameter, add parameter to
OsmoNITB's main adoc and move smpp.adoc to common/chapters.

Change-Id: I15febdea6569316dad3eed5f9dc7158adb5b078c

1 files changed, 147 insertions, 0 deletions

diff --git a/common/chapters/smpp.adoc b/common/chapters/smpp.adoc
new file mode 100644
index 0000000..e62a844
--- /dev/null
+++ b/common/chapters/smpp.adoc
@@ -0,0 +1,147 @@
+[[smpp]]
+== Short Message Peer to Peer (SMPP)
+
+The _Short Message Peer to Peer (SMPP) Protocol_ <<smpp-34>> has been
+used for the communication with SMSCs. Osmocom implements version 3.4
+of the protocol. Using this interface one can send MT-SMS to an attached
+subscriber or receive unrouted MO-SMS.
+
+SMPP is served by the Osmocom MSC layer (both in the old OsmoNITB as well as
+the new OsmoMSC.
+
+SMPP describes a situation where multiple ESMEs (External SMS Entities)
+interact with a SMSC (SMS Service Center) via the SMPP protocol.  Each
+entity is identified by its System Id.  The System ID is a character
+string which is configured by the system administrator.
+
+{program-name} implements the SMSC side of SMPP and subsequently acts as a TCP
+server accepting incoming connections from ESME client programs.
+
+Each ESME identifies itself to the SMSC with its system-id and an
+optional shared password.
+
+
+=== Global SMPP configuration
+
+
+There is a `smpp` vty node at the top level of the {program-name}
+configuration. Under this node, the global SMPP configuration is
+performed.
+
+
+Use the `local-tcp-ip` command to define the TCP IP and port at which the
+{program-name} internal SMSC should listen for incoming SMPP connections.  The
+default behaviour is to listen on all IPs (0.0.0.0), and the default port
+assigned to SMPP is 2775.
+
+Use the `system-id` command to define the System ID of the SMSC.
+
+Use the `policy` parameter to define whether only explicitly configured
+ESMEs are permitted to access the SMSC (`closed`), or whether any
+ESME should be accepted (`accept-all`).
+
+Use the `smpp-first` command to define if SMPP routes have higher
+precedence than MSISDNs contained in the HLR (`smpp-first`), or if
+only MSISDNs found not in the HLR should be considered for routing to
+SMPP (`no smpp-first`).
+
+
+=== ESME configuration
+
+Under the `smpp` vty node, you can add any number of `esme` nodes, one
+for each ESME that you wish to configure.
+
+Use the `esme NAME` command (where NAME corresponds to the system-id of
+the ESME to be configured) under the SMPP vty node to enter the
+configuration node for this given ESME.
+
+Use the `password` command to specify the password (if any) for the
+ESME.
+
+Use the `default-route` command to indicate that any MO-SMS without a
+more specific route should be routed to this ESME.
+
+Use the `deliver-src-imsi` command to indicate that the SMPP DELIVER
+messages for MO SMS and the SMPP ALERT should state the IMSI (rather
+than the MSISDN) as source address.
+
+Use the `osmocom-extensions` command to request that Osmocom specific
+extension TLVs shall be included in the SMPP PDUs.  Those extensions
+include the ARFCN of the cell, the L1 transmit power of the MS, the
+timing advance, the uplink and dwnlink RxLev and RxQual, as well as the
+IMEI of the terminal at the time of generating the SMPP DELIVER PDU.
+
+Use the `dcs-transparent` command to transparently pass the DCS value
+from the SMS Layer3 protocols to SMPP, instead of converting them to the
+SMPP-specific values.
+
+Use the `route prefix` command to specify a route towards this ESME.
+Using routes, you specify which destination MSISDNs should be routed
+towards your ESME.
+
+
+=== Example configuration snippet
+
+The following example configuration snippet shows a single ESME
+'galactica' with a prefix-route of all national numbers stating with
+2342:
+
+----
+smpp
+ local-tcp-port 2775
+ policy closed
+ no smpp-first
+ esme galactica
+  password SoSayWeAll
+  deliver-src-imsi
+  osmocom-extensions
+   route prefix national isdn 2342
+----
+
+
+=== Osmocom SMPP protocol extensions
+
+Osmocom has implemented some extensions to the SMPP v3.4 protocol.
+
+These extensions can be enabled using the `osmocom-extensions` VTY
+command at `esme` level.
+
+The TLV definitions can be found in the
+`<osmocom/gsm/protocol/smpp34_osmocom.h>` header file provided by
+libosmocore.
+
+==== RF channel measuremets
+
+When the Osmocom SMPP extensions are enabled, we add the following
+TLVs to each SMPP DELIVER PDU:
+
+[options="header", cols="3,1,1,5"]
+|===
+| TLV | IEI | Length (Octets) | Purpose
+| TLVID_osmo_arfcn | 0x2300 | 2 | GSM ARFCN of the radio interface
+| TLVID_osmo_ta | 0x2301 | 1 | Timing Advance on the radio interface
+| TLVID_osmo_ms_l1_txpwr | 0x2307 | 1 | Transmit Power of the MS in uplink direction
+| TLVID_osmo_rxlev_ul | 0x2302 | 2 | Uplink receive level as measured by BTS in dBm (int16_t)
+| TLVID_osmo_rxqual_ul | 0x2303 | 1 | Uplink RxQual value as measured by BTS
+| TLVID_osmo_rxlev_dl | 0x2304 | 2 | Downlink receive level as measured by MS in dBm (int16_t)
+| TLVID_osmo_rxqual_dl | 0x2305 | 1 | Downlink RxQual value as measured by MS
+|===
+
+All of the above values reflect the *last measurement report* as
+recieved vi A-bis RSL from the BTS.  It is thus a snapshot value (of
+the average within one 480ms SACCH period), and not an average over
+all the SACCH periods during which the channel was open or the SMS was
+received. Not all measurement reports contain all the values.  So you
+might not get an TLVID_osmo_rxlev_dl IE, as that particular uplink
+frame might habe benn lost for the given snapshot we report.
+
+==== Equipment IMEI
+
+If we know the IMEI of the subscribers phone, we add the following TLV
+to each SMPP DELIVER PDU:
+
+[options="header", cols="3,1,1,5"]
+|===
+| TLV | IEI | Length | Purpose
+| TLVID_osmo_imei | 0x2306 | variable | IMEI of the subscibers phone (ME)
+|===