[[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
received 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 subscribers phone (ME)
|===
