doc/manuals/chapters/ussd.adoc

[[ussd]]
== Unstructured Supplementary Services Data (USSD)

The _Unstructured Supplementary Services Data (USSD)_ is one service within
2G/3G networks next to other services such as circuit-switched voice, packet-switched
data and SMS (Short Message Service).

It is on an abstract level quite similar to SMS in that USSD can be used to send
textual messages.  However, there are the following differences:

* USSD is between the MS (phone) and an USSD application on the network, while
  SMS is primarily between two subscribers identified by their MSISDN
* USSD is faster, as it doesn't suffer from the complicated three-layer CP/RP/TP
  protocol stack of SMS with it's acknowledgement of the acknowledged acknowledgement.
* USSD is session-oriented, i.e. a dialogue/session between subscriber and application
  can persist for the transfer of more than one message.  The dedicated radio channel
  on the RAN remains established throughout that dialogue.

=== USSD in Osmocom

Until August 2018, OsmoMSC contained some minimalistic internal USSD
handling with no
ability to attach/extend it with external USSD applications.

From August 2018 onwards, OsmoMSC doesn't contain any internal USSD
handlers/applications anymore.  Instead, all USSD is transported to/from
OsmoHLR via the GSUP protocol.

OsmoHLR contains some intenal USSD handlers and can route USSD messages
to any number of external USSD entities (EUSEs).  The EUSE also use GSUP
to communicate USSD from/to OsmoHLR.

Each EUSE is identified by its name.  The name consists of a single-word
string preceding a currently fixed ("-00-00-00-00-00-00") suffix.
There is no authentication between EUSE and OsmoHLR: Any client program
able to connect to the GSUP port of OsmoHLR can register as any EUSE
(name).

NOTE:: We plan to remove the requirement for this suffix as soon as we
are done resolving all more important issues.

=== USSD Configuration

USSD configuration in OsmoHLR happens within the `hlr` VTY node.

`euse foobar-00-00-00-00-00-00` defines an EUSE with the given name `foobar`

`ussd route prefix *123 external foobar-00-00-00-00-00-00` installs a
prefix route to the named EUSE.  All USSD short codes starting with *123 will be
routed to the named EUSE.

`ussd route prefix *#100# internal own-msisdn` installs a prefix route
to the named internal USSD handler.  The above command will restore
the old behavior, in which *#100# will return a text message containing
the subscribers own phone number.  More information on internal USSD
handlers can be found in <<iuse_handlers>>.

`ussd default-route external foobar-00-00-00-00-00-00` installs a
default route to the named EUSE.  This means that all USSD codes for
which no more specific route exists will be routed to the named EUSE.

[[iuse_handlers]]
=== Built-in USSD handlers

OsmoHLR has an Internal USSD Entity (IUSE) that allows to handle some
USSD requests internally.  It features a set of simple handlers, which
can be assigned to one or more USSD request prefixes:

* `own-msisdn` returns subscriber's MSISDN (if assigned);
* `own-imsi` returns subscriber's IMSI;
* `test-idle` keeps the session idle until the MS terminates it, or
  the guard timer expires (may be useful for testing).

Additional handlers can be added on request.

=== Example EUSE program

We have provided an example EUSE developed in C language using existing
Osmocom libraries for GSUP protocol handling and USSD encoding/decoding.
It will register as `foobar` EUSE to OsmoHLR on localhost.  You can run
it on a different machine by specifying e.g. `osmo-euse-demo 1.2.3.4 5678`
to make it connect to OsmoHLR on IP address 1.2.3.4 and GSUP/TCP port
5678.

The idea is that you can use this as a template to develop your own USSD
applications, or any gateways to other protocols or interfaces.

You can find it in `osmo-hlr/src/osmo-euse-demo.c` or online by
following the link to http://git.osmocom.org/osmo-hlr/tree/src/osmo-euse-demo.c

This demonstration program will echo back any USSD message sent/routed
to it, quoted like _You sent "..."_.