USSD
This document describes the Unstructured Supplementary Service Data (USSD) implementation in OmniMSC, covering HLR relay, local handling, the diagnostic easter egg menu, the USSD codec, and the SS message flow.
For supplementary service codes handled via USSD (call forwarding MMI codes, call barring, call waiting), see Supplementary Services. For the MAP ProcessUnstructuredSS-Request operation and dialogue management, see MAP Operations. For USSD-related Prometheus metrics, see Metrics and Monitoring. For USSD gateway configuration, see Configuration Reference. For troubleshooting USSD issues, see Troubleshooting.
USSD Relay to HLR
When a subscriber sends a USSD string that is not handled locally by the MSC, the request is relayed to the HLR via MAP. The MS sends a REGISTER message containing a Facility IE with a processUnstructuredSS-Request (opcode 59). The MSC extracts the USSD string and forwards the request to the HLR using the same MAP operation.
For multi-step interactive sessions, the HLR responds with an unstructuredSS-Request (opcode 60) instead of a final response. The MSC relays this to the UE as a FACILITY message, and the UE's reply is forwarded back to the HLR. This dialogue continues until the HLR sends a final processUnstructuredSS-Response.
Local USSD Handling
The MSC can handle certain USSD codes locally without forwarding to the HLR or an external gateway. Local handling is used for:
- Supplementary service activation/deactivation codes (CFU, CFB, CFNR, CFNRC, CLIP, CLIR, Call Barring, Call Waiting) using the standard MMI format defined in 3GPP TS 22.030
- Operator-defined diagnostic codes handled internally by the MSC
When a USSD string matches a locally handled service code, the USSD Handler routes it to the SS Handler or the appropriate internal module. The response is sent directly to the UE without MAP signaling.
For codes in the operator-defined range (100-199), the USSD Gateway module routes the request to an external USSD gateway if one is configured, or rejects the request if no gateway is available.
Easter Egg: System Diagnostic Menu
OmniMSC includes a hidden diagnostic menu accessible by dialing *#6664# (which spells *#OMNI# on a phone keypad). The MSC recognizes several keypad variants of this code and responds with an interactive USSD menu.
The main menu provides the following options:
| Key | Menu Item | Information Displayed |
|---|---|---|
| 1 | System Status | Uptime, registered subscribers, active connections, active calls, memory usage, scheduler count |
| 2 | VLR | Registered subscriber count, active LU FSMs, active Auth FSMs |
| 3 | Active Calls | Count and summary of active calls (direction, calling/called numbers) |
| 4 | SS7 Stack | SCCP connection count, TCAP transaction count, pending paging requests |
| 5 | BEAM VM | Process count/limit, run queue depth, reduction count, memory breakdown (total, ETS, binary) |
| 6 | About | OmniMSC version info, OTP release, Omnitouch Network Services branding |
| 9 | Sales Enquiry | Contact information |
| 0 | Exit | Ends the session |
Each submenu displays a "0. Back" option that returns to the main menu. The diagnostic data is gathered from live system metrics at the time of the request.
The easter egg is handled entirely within the MSC without any MAP signaling. The USSD Handler detects the magic code, routes it to the EasterEgg module, and manages the multi-step menu dialogue using network-initiated unstructuredSS-Request messages to the UE.
USSD Codec
The USSD codec handles encoding and decoding of USSD protocol elements per 3GPP TS 24.080 and TS 24.090.
Facility IE Structure
The Facility IE (tag 0x1C) wraps an ASN.1 BER-encoded component:
| Component Type | ASN.1 Tag | Usage |
|---|---|---|
| Invoke | 0xA1 | Carries a request (processUnstructuredSS-Request, unstructuredSS-Request, unstructuredSS-Notify) |
| ReturnResultLast | 0xA2 | Carries a response (processUnstructuredSS-Response, unstructuredSS-Response) |
Each component contains an invoke ID, an operation code, and an optional parameter SEQUENCE with the USSD data coding scheme and USSD string.
MAP Operation Codes
| Opcode | Operation | Direction |
|---|---|---|
| 59 | processUnstructuredSS-Request | MO: UE → MSC → HLR |
| 60 | unstructuredSS-Request | MT: HLR → MSC → UE (interactive menu step) |
| 61 | unstructuredSS-Notify | MT: HLR → MSC → UE (notification, no response expected) |
GSM 7-bit Encoding
USSD strings are encoded using the GSM 7-bit default alphabet defined in 3GPP TS 23.038. Each character is represented as a 7-bit septet, and septets are packed into octets (8 septets fit into 7 bytes). The data coding scheme byte (DCS=0x0F) indicates GSM 7-bit encoding.
For strings requiring characters outside the GSM 7-bit alphabet, UCS-2 encoding (DCS=0x48) is used, where each character occupies two bytes in big-endian UTF-16.
The maximum USSD string length is 182 characters for GSM 7-bit encoding (160 bytes packed) or 80 characters for UCS-2 (160 bytes).
SS REGISTER and RELEASE COMPLETE Message Flow
USSD sessions use the Supplementary Service (SS) message types defined in 3GPP TS 24.010:
| Message | Direction | Purpose |
|---|---|---|
| REGISTER | UE → MSC | Initiates a new SS transaction. Contains a Facility IE with the USSD request. |
| FACILITY | Both | Carries mid-session data (interactive menu steps). Used for multi-step USSD dialogues. |
| RELEASE COMPLETE | Both | Ends the SS transaction. May contain a Facility IE with the final response. |
A simple USSD request-response uses REGISTER (from UE) followed by RELEASE COMPLETE (from MSC). An interactive multi-step session uses REGISTER, then one or more FACILITY exchanges, then RELEASE COMPLETE.
The session has a configurable guard timeout (default 30 seconds). If neither the UE nor the gateway responds within this window, the MSC terminates the session with RELEASE COMPLETE.
References
| Specification | Title | Relevance |
|---|---|---|
| TS 24.090 | Unstructured Supplementary Service Data (USSD) | USSD procedures, session management |
| TS 29.002 Section 14 | MAP Specification - Supplementary service operations | MAP processUnstructuredSS-Request (opcode 59), unstructuredSS-Request (opcode 60), unstructuredSS-Notify (opcode 61) |
| TS 24.080 | Mobile radio interface layer 3 SS specification - Formats and coding | Facility IE structure, component encoding |
| TS 23.038 | Alphabets and language-specific information | GSM 7-bit default alphabet, septet packing |
| TS 22.030 | Man-Machine Interface (MMI) | Service code format, USSD string syntax |
| TS 24.010 | Mobile radio interface layer 3 SS specification - General aspects | REGISTER, FACILITY, RELEASE COMPLETE message types |