Harald Welte | b41394a | 2018-08-06 22:18:33 +0200 | [diff] [blame] | 1 | [[ussd]] |
| 2 | == Unstructured Supplementary Services Data (USSD) |
| 3 | |
| 4 | The _Unstructured Supplementary Services Data (USSD)_ is one service within |
| 5 | 2G/3G networks next to other services such as circuit-switched voice, packet-switched |
| 6 | data and SMS (Short Message Service). |
| 7 | |
| 8 | It is on an abstract level quite similar to SMS in that USSD can be used to send |
| 9 | textual messages. However, there are the following differences: |
| 10 | |
| 11 | * USSD is between the MS (phone) and an USSD application on the network, while |
| 12 | SMS is primarily between two subscribers identified by their MSISDN |
| 13 | * USSD is faster, as it doesn't suffer from the complicated three-layer CP/RP/TP |
| 14 | protocol stack of SMS with it's acknowledgement of the acknowledged acknowledgement. |
| 15 | * USSD is session-oriented, i.e. a dialogue/session between subscriber and application |
| 16 | can persist for the transfer of more than one message. The dedicated radio channel |
| 17 | on the RAN remains established throughout that dialogue. |
| 18 | |
| 19 | === USSD in Osmocom |
| 20 | |
| 21 | Until August 2018, OsmoMSC contained some minimalistic internal USSD |
| 22 | handling with no |
| 23 | ability to attach/extend it with external USSD applications. |
| 24 | |
| 25 | From August 2018 onwards, OsmoMSC doesn't contain any internal USSD |
| 26 | handlers/applications anymore. Instead, all USSD is transported to/from |
| 27 | OsmoHLR via the GSUP protocol. |
| 28 | |
| 29 | OsmoHLR contains some intenal USSD handlers and can route USSD messages |
| 30 | to any number of external USSD entities (EUSEs). The EUSE also use GSUP |
| 31 | to communicate USSD from/to OsmoHLR. |
| 32 | |
| 33 | Each EUSE is identified by its name. The name consists of a single-word |
| 34 | string preceding a currently fixed ("-00-00-00-00-00-00") suffix. |
| 35 | There is no authentication between EUSE and OsmoHLR: Any client program |
| 36 | able to connect to the GSUP port of OsmoHLR can register as any EUSE |
| 37 | (name). |
| 38 | |
| 39 | NOTE:: We plan to remove the requirement for this suffix as soon as we |
| 40 | are done resolving all more important issues. |
| 41 | |
| 42 | === USSD Configuration |
| 43 | |
| 44 | USSD configuration in OsmoHLR happens within the `hlr` VTY node. |
| 45 | |
| 46 | `euse foobar-00-00-00-00-00-00` defines an EUSE with the given name `foobar` |
| 47 | |
| 48 | `ussd route prefix *123 external foobar-00-00-00-00-00-00` installs a |
| 49 | prefix route to the named EUSE. All USSD short codes starting with *123 will be |
| 50 | routed to the named EUSE. |
| 51 | |
| 52 | `ussd route prefix *#100# internal own-msisdn` installs a prefix route |
| 53 | to the named internal USSD handler. There above command will restore |
| 54 | the old behavior, in which *#100# will return a text message containing |
| 55 | the subscribers own phone number. There is one other handler called |
| 56 | `own-imsi` which will return the IMSI instead of the MSISDN. |
| 57 | |
| 58 | `ussd default-route external foobar-00-00-00-00-00-00` installs a |
| 59 | default route to the named EUSE. This means that all USSD codes for |
| 60 | which no more specific route exists will be routed to the named EUSE. |
| 61 | |
| 62 | === Example EUSE program |
| 63 | |
| 64 | We have provided an example EUSE developed in C language using existing |
| 65 | Osmocom libraries for GSUP protocol handling and USSD encoding/decoding. |
| 66 | It will register as `foobar` EUSE to OsmoHLR on localhost. You can run |
| 67 | it on a different machine by specifying e.g. `osmo-euse-demo 1.2.3.4 5678` |
| 68 | to make it connect to OsmoHLR on IP address 1.2.3.4 and GSUP/TCP port |
| 69 | 5678. |
| 70 | |
| 71 | The idea is that you can use this as a template to develop your own USSD |
| 72 | applications, or any gateways to other protocols or interfaces. |
| 73 | |
| 74 | You can find it in `osmo-hlr/src/osmo-euse-demo.c` or online by |
| 75 | following the link to http://git.osmocom.org/osmo-hlr/tree/src/osmo-euse-demo.c |
| 76 | |
| 77 | This demonstration program will echo back any USSD message sent/routed |
| 78 | to it, quoted like _You sent "..."_. |