Difference between revisions of "USSD GW"
From ss7api.null.ro
(→ussd.execute) |
(→Keyword values) |
||
| (14 intermediate revisions by one user not shown) | |||
| Line 38: | Line 38: | ||
* network notification requests. | * network notification requests. | ||
| − | User interaction requests are USSD requests that the network makes in which it requires some type of information back from the mobile subscriber. These are started by the network through a TCAP BEGIN containing an ''unstructuredSS-Request'' Invoke. The answer from the mobile subscriber will be received in a TCAP CONTINUE containing an ''unstructuredSS-Request'' ResultLast. If the network still wants to request further information | + | User interaction requests are USSD requests that the network makes in which it requires some type of information back from the mobile subscriber. These are started by the network through a TCAP BEGIN containing an ''unstructuredSS-Request'' Invoke. The answer from the mobile subscriber will be received in a TCAP CONTINUE containing an ''unstructuredSS-Request'' ResultLast. If the network still wants to request further information from the user it can send another ''unstructuredSS-Request'' Invoke in a TCAP CONTINUE and wait for the answer. Once the network obtains all needed information, but wants (for user friendliness) to notify the user about the result of the operations, it can send: |
| + | * a TCAP CONTINUE containing a ''unstructuredSS-Notify'' Invoke. When the user side respond with a TCAP CONTINUE containing an empty ''unstructuredSS-Notify'', the network can close the dialog through a TCAP END | ||
| + | * if the network is not interested in the outcome of ''unstructuredSS-Notify'' Invoke operation, it can send a TCAP END containing ''unstructuredSS-Notify'' invoke. | ||
| + | If there is nothing to notify to the user, the network can send a TCAP END to close the TCAP dialog. | ||
| + | |||
| + | |||
Network notification requests are USSD requests in which the network only sends a notification to the user. This is achieved by sending a TCAP BEGIN message containing a ''unstructuredSS-Notify'' Invoke. The mobile subscriber side will only respond with a TCAP CONTINUE containing an empty ''unstructuredSS-Notify'' in order to signal that the notification was received. The network will close the TCAP dialog through TCAP END. | Network notification requests are USSD requests in which the network only sends a notification to the user. This is achieved by sending a TCAP BEGIN message containing a ''unstructuredSS-Notify'' Invoke. The mobile subscriber side will only respond with a TCAP CONTINUE containing an empty ''unstructuredSS-Notify'' in order to signal that the notification was received. The network will close the TCAP dialog through TCAP END. | ||
| Line 393: | Line 398: | ||
** type: boolean | ** type: boolean | ||
** True if the language was decoded from the USSD string and not from the data coding scheme or if should be encoded on MAP in the USSD string payload. | ** True if the language was decoded from the USSD string and not from the data coding scheme or if should be encoded on MAP in the USSD string payload. | ||
| + | ** Set to false for UCS2 encoding without language indication | ||
* imsi: | * imsi: | ||
** type: string | ** type: string | ||
| Line 484: | Line 490: | ||
** type: hexified string | ** type: hexified string | ||
** The encoded USSD string | ** The encoded USSD string | ||
| + | ** '''NOTE''': If YATE uses in the internal messages the decoded text, this parameter should not be set (it has higher priority in ussd_map). | ||
* text: | * text: | ||
** type: string | ** type: string | ||
| Line 496: | Line 503: | ||
** type: boolean | ** type: boolean | ||
** True if the language was decoded from the USSD string and not from the data coding scheme or if should be encoded on MAP in the USSD string payload. | ** True if the language was decoded from the USSD string and not from the data coding scheme or if should be encoded on MAP in the USSD string payload. | ||
| + | ** Set to false for UCS2 encoding without language indication | ||
* error: | * error: | ||
** type: keyword | ** type: keyword | ||
| Line 533: | Line 541: | ||
* text_encoded: | * text_encoded: | ||
** type: hexified string | ** type: hexified string | ||
| + | ** '''NOTE''': If YATE uses in the internal messages the decoded text, this parameter should not be set (it has higher priority in ussd_map). | ||
** The encoded USSD string | ** The encoded USSD string | ||
* text: | * text: | ||
| Line 546: | Line 555: | ||
** type: boolean | ** type: boolean | ||
** True if the language was decoded from the USSD string and not from the data coding scheme or if should be encoded on MAP in the USSD string payload. | ** True if the language was decoded from the USSD string and not from the data coding scheme or if should be encoded on MAP in the USSD string payload. | ||
| + | ** Set to false for UCS2 encoding without language indication | ||
* error: | * error: | ||
** type: keyword | ** type: keyword | ||
| Line 604: | Line 614: | ||
** protocol_error: SMPP generic error. This error is put whenever there is a SMPP specific error that cannot be mapped into one of the other errors. | ** protocol_error: SMPP generic error. This error is put whenever there is a SMPP specific error that cannot be mapped into one of the other errors. | ||
| + | * '''node''' | ||
| + | ** MAP parameter for when error = system_failure | ||
| + | ** maps to networkResource in the MAP Error. | ||
| + | ** possible values are: plmn, hlr, vlr, pvlr, controllingMSC, vmsc, eir, rss. Defaults to plmn if not given | ||
| + | |||
| + | * '''cause''' | ||
| + | ** MAP parameter for when error = call_barred | ||
| + | ** maps to callBarringCause in the MAP Error | ||
| + | ** possible values are: barringServiceActive, operatorBarring. Defaults to operatorBarring if not given | ||
| + | |||
| + | * '''text.encoding''' | ||
| + | ** gsm7bit / GSM7Bit: text was encoded/is to be encoded GSM 7 Bit | ||
| + | ** ucs2 / UCS2: text was encoded/is to be encoded UCS 2 | ||
| + | |||
| + | * '''text.lang''' | ||
| + | ** two character string specifying a language according to ISO 639-1 or integer value if mapping is not provided. | ||
==== SMPP custom parameters ==== | ==== SMPP custom parameters ==== | ||
| Line 719: | Line 745: | ||
==== camel_map module ==== | ==== camel_map module ==== | ||
| + | |||
| + | '''NOTE''': As of SVN revision 1285, there is a new ''camelmap'' module. For compatibility reasons, the old module, ''camel_map'', was also kept. Both modules read the same configuration file, ''camel_map.conf''. In order to avoid issues, please make sure to only enable one of these modules in the ''[postload]'' section of ''yate.conf''. | ||
| + | |||
| + | The new module is the one that offers USSD UCS2 encoding without language indication, but beware that TCP functionality has been removed from it. That functionality has been moved to the ''xml_tcp'' module. The module only uses messages to communicate with applications. ''ussd_map'' uses messages, so there should be no need for TCP functionality. | ||
| + | |||
Configuring of tracking IDs is done in the ''general'' section: | Configuring of tracking IDs is done in the ''general'' section: | ||
| Line 833: | Line 864: | ||
add-encoding=false | add-encoding=false | ||
| − | [local | + | [local ussdscf1] |
translator=scf | translator=scf | ||
capabilities=USSD | capabilities=USSD | ||
export_xml_as=object | export_xml_as=object | ||
ussd-string=octets | ussd-string=octets | ||
| − | ussd-decode= | + | ussd-decode=all |
| − | [local | + | [local ussdscf2] |
translator=scf | translator=scf | ||
capabilities=USSD | capabilities=USSD | ||
export_xml_as=object | export_xml_as=object | ||
ussd-string=octets | ussd-string=octets | ||
| − | ussd-decode= | + | ussd-decode=all |
| − | [local | + | [local ussdhlr1] |
translator=hlr | translator=hlr | ||
capabilities=USSD | capabilities=USSD | ||
export_xml_as=object | export_xml_as=object | ||
ussd-string=octets | ussd-string=octets | ||
| − | ussd-decode= | + | ussd-decode=all |
| − | [local | + | [local ussdhlr2] |
translator=hlr | translator=hlr | ||
capabilities=USSD | capabilities=USSD | ||
export_xml_as=object | export_xml_as=object | ||
ussd-string=octets | ussd-string=octets | ||
| − | ussd-decode= | + | ussd-decode=all |
| + | |||
| + | '''Note''' If SMPP is configured to expect decoded USSD texts (which is the default configuration), the ''ussd-decode'' configuration setting should be set to ''all''. | ||
==== ussd_map module ==== | ==== ussd_map module ==== | ||
| Line 990: | Line 1,023: | ||
floodevents=1000 | floodevents=1000 | ||
| − | [ | + | [ussdscf1] |
;enable=no | ;enable=no | ||
type=SCF | type=SCF | ||
| Line 1,013: | Line 1,046: | ||
default_addr.CalledPartyAddress.gt.encoding=bcd | default_addr.CalledPartyAddress.gt.encoding=bcd | ||
| − | [ | + | [ussdscf2] |
;enable=no | ;enable=no | ||
type=SCF | type=SCF | ||
| Line 1,036: | Line 1,069: | ||
default_addr.CalledPartyAddress.gt.encoding=bcd | default_addr.CalledPartyAddress.gt.encoding=bcd | ||
| − | [ | + | [ussdhlr1] |
;enable=no | ;enable=no | ||
type=HLR | type=HLR | ||
| Line 1,059: | Line 1,092: | ||
default_addr.CalledPartyAddress.gt.encoding=bcd | default_addr.CalledPartyAddress.gt.encoding=bcd | ||
| − | [ | + | [ussdhlr2] |
;enable=no | ;enable=no | ||
type=HLR | type=HLR | ||
| Line 1,085: | Line 1,118: | ||
TODO - configuration explanations | TODO - configuration explanations | ||
| + | |||
| + | |||
| + | '''NOTE''' The module encodes text to ASCII for default encoding (configuration parameter ''default_encoding_type''). If you want to send GSM 7 Bit for SMPP default encoding, please see how the setting is set below. | ||
'''Configuration Example'''' | '''Configuration Example'''' | ||
| Line 1,103: | Line 1,139: | ||
;enable=yes | ;enable=yes | ||
addr=0.0.0.0 | addr=0.0.0.0 | ||
| − | port=12345 | + | port=12345 |
| − | + | ; use GSM 7 Bit for default SMPP encoding | |
| + | default_encoding_type=gsm7bit | ||
=== Monitoring === | === Monitoring === | ||
Latest revision as of 17:35, 14 September 2015
This is an implementation an USSD gateway acting as a MAP Service Control Function (gsmSCF) and as a HLR at the same time. When communicating with a HLR or VLR, the YATE USSD GW acts as a gsmSCF. When communicating with a gsmSCF, the YATE USSDGW acts as a HLR. The functionality of the USSD GW allows:
- redirecting of USSD requests arriving either from user side or gsmSCF side to a SMPP client where they can be altered.
- acting as a proxy for requests that need not be handled by SMPP clients or when the SMPP handling fails
Contents |
[edit] MAP USSD description
In versions 2 and 3 of the GSM MAP protocol there are 3 operations used for USSD operations:
- processUnstructedSS-Request
- unstructuredSS-Request
- unstrusturedSS-Notify
The are 2 scenarios for USSD operations:
- mobile initiated USSD requests
- network initiated USSD requests
A TCAP dialog used by USSD is always terminated by the network side.
[edit] Mobile initiated USSD requests
Mobile initiated USSD requests are USSD requests started by the mobile subscriber.
A USSD request is started when receiving a TCAP BEGIN message containing the processUnstructedSS-Request Invoke operation. The request can be handled by the VLR, HLR or a gsmSCF. If the VLR does not handle the request, it will transmit it to the HLR. The HLR can either handle it itself or it can transmit it to a gsmSCF for handling.
At this point, the network can either send a response to the request immediately or request additional information. In the first case, the handler of the request will send a TCAP End with processUnstructuredSS-Request ResultLast containing the result for the request. In the latter case, the network will send a TCAP CONTINUE with unstructuredSS-Request Invoke operation. The response of the mobile subscriber to this request will be passed to the network in a TCAP CONTINUE with unstructuredSS-Request ResultLast component. At this point, if the network decides that it has enough information for providing the response to the user, it will send a TCAP END with processUnstructuredSS-Request ResultLast. Otherwise, it can request further information through another unstructuredSS-Request Invoke operation.
[edit] Network initiated USSD requests
Network initiated USSD requests are USSD requests started by the network towards a certain subscriber.
Requests made by the network can be of one of two types:
- user interaction requests
- network notification requests.
User interaction requests are USSD requests that the network makes in which it requires some type of information back from the mobile subscriber. These are started by the network through a TCAP BEGIN containing an unstructuredSS-Request Invoke. The answer from the mobile subscriber will be received in a TCAP CONTINUE containing an unstructuredSS-Request ResultLast. If the network still wants to request further information from the user it can send another unstructuredSS-Request Invoke in a TCAP CONTINUE and wait for the answer. Once the network obtains all needed information, but wants (for user friendliness) to notify the user about the result of the operations, it can send:
- a TCAP CONTINUE containing a unstructuredSS-Notify Invoke. When the user side respond with a TCAP CONTINUE containing an empty unstructuredSS-Notify, the network can close the dialog through a TCAP END
- if the network is not interested in the outcome of unstructuredSS-Notify Invoke operation, it can send a TCAP END containing unstructuredSS-Notify invoke.
If there is nothing to notify to the user, the network can send a TCAP END to close the TCAP dialog.
Network notification requests are USSD requests in which the network only sends a notification to the user. This is achieved by sending a TCAP BEGIN message containing a unstructuredSS-Notify Invoke. The mobile subscriber side will only respond with a TCAP CONTINUE containing an empty unstructuredSS-Notify in order to signal that the notification was received. The network will close the TCAP dialog through TCAP END.
[edit] MAP USSD parameters
The following list describe common parameters used across all MAP USSD operations:
- destinationReference: this parameter will contain either an MSISDN or an IMSI. In the case of mobile originated USSD request, this will identify the user which made the request. In the case of network initiated requests, it will identify the mobile user to be contacted for this request.
- ussd-String: for processUnstructuredSS-Request Invoke it contains the dialed USSD code, for the result it would probably contain a message from the network detailing the result of the request. For unstructuredSS-Request Invoke it will contain a message asking for the user to choose some option and for the result it will contain the option chosen by the user. In the case of unstructuredSS-Notify, this parameter will only be present in the Invoke.
- ussd-DataCodingScheme: this is a parameter which specifies in which way the ussd-String parameter is encoded and it is present whenever ussd-String is present. E.g., this parameter would indicate if the ussd-String is encoded using GSM7bit encoding or UCS2.
[edit] SMPP USSD description
TO DO
[edit] System description
[edit] System design
In order to provide the specified functionality, the system makes use of the following YATE components:
- the SS7 stack present in YATE
- the camel_map module which decodes/encodes MAP messages coming from the SS7 network to/from internal YATE messages containing MAP operations in XML form. Together with the SS7 layer this provides MAP connectivity with HLR/gsmSCF.
- the ussd_map module which takes internal MAP messsages decoded by the camel_map moduled and translates them to internal USSD messages. This module acts as gsmSCF towards a HLR and as a HLR towards a gsmSCF.
- the SMPP stack present in YATE (ysmpp module) which is able to catch internal USSD messages and transmit them over SMPP. It also translates SMPP messages into internal USSD messages.
- requests for new USSD sessions will go through routing to decide who should handle the request.
The following sections detail the behaviour of the system in the different USSD scenarios.
[edit] Mobile originated USSD handling
A user initiated USSD session is handled according to the following schema:
- HLR sends a processUnstructuredSS-Request (Invoke) for code *100#. camel_map decodes the ussd-String into ussd-Text=*100#.
- the ussd_map module (gsmSCF side) processes the request received from the HLR and emits a call.route message with called=*100#.
- After ussd_map module successfully dispatched the call.route message, it generates a ussd.execute message with the callto parameter set to the value returned from routing. ussd_map dispatches the ussd.execute message.
- The ysmpp module catches the ussd.execute message and if the callto param value starts with ysmppserver/ and with it it builds a deliver_sm message that it will send it to the target specified in callto parameter after the module prefix ysmppserver/.
- The ysmpp module receives and process the received submit_sm message.
- The ysmpp module will send a call.route message with the called=*100#.
- The ysmpp module emits a ussd.execute message with callto=retvalue from call.route message.
- The ussd_map module (HLR part) processes the ussd.execute message and if it is the target of the message, meaning that callto starts with ussd_map/. From that message it will build a map.message that it will send to the gsmSCF as a processUnstructuresSS-Request (Invoke) MAP message.
NOTE: From here on, the gsmSCF could handle the request in one of two distinguished cases: one where the gsmSCF requires interaction with the mobile subscriber and one where the gsmSCF just needs to respond to the user request. The following steps detail the former case.
- gsmSCF sends an unstructuredSS-Request (Invoke) to request further information.
- The ussd_map module (HLR part) processes the unstructuredSS-Request (Invoke) message and emits an ussd.update message.
- The ysmpp module receives the ussd.update message and confirms to the SMPP client that the message sent in step 5 was processed.
- The SMPP client should confirm the processing of the SMPP message sent in step 4.
- The ysmpp module sends a deliver_sm message to the SMPP client with the menu received in ussd.update message.
- The SMPP client should send a submit_sm message with the received menu.
- The ysmpp module receives the submit_sm message from SMPP client and emits a ussd.update message.
- The ussd_map module (SCF part) process the ussd.update message and sends an unstructuredSS-Request (Invoke) towards the HLR.
The time in which the mobile subscribers responds can be quite long.
- The HLR sends unstructuredSS-Request (ResultLast) to USSD gateway when receiving the response from the mobile subscriber.
- The ussd_map module (SCF part) processes the message and emits a ussd.update message.
- ysmpp module processes the ussd.update message and sends submit_sm rsp to SMPP client to confirm the reception of the message sent on step 14.
- The SMPP client should send a deliver_sm rsp to confirm the message received on step 13.
- The ysmpp module will send a deliver_sm message to SMPP clients which will contain user's response.
- The SMPP client should send a submit_sm message to SMPP server which will contain the message received on step 21.
- The ysmpp module receives the submit_sm message and emits a ussd.update message.
- The ussd_map module (HLR part) receives the ussd.update message and sends the unstructuredSS-Request (ResultLast) to gsmSCF.
NOTE: Steps between 9 and 24 can be repeated.
- The gsmSCF sends processUnstructuredSS-Request (ResultLast) for the initial user request.
- The ussd_map module (HLR part) processes the processUnstructuredSS-Request (ResultLast) and sends a ussd.finalize message.
- The ysmpp module receives the ussd.finalize message and sends a submit_sm rsp for the message received on point 22 or 5.
- The SMPP client should send a deliver_sm rsp for the message received on point 21 or 4.
- The ysmpp module sends a deliver sm + last message indication to SMPP client.
- The SMPP client should send a submit sm + last message indication to SMPP server.
- ysmpp module receives submit_sm message and sends a ussd.finalize message.
- ysmpp module sends submit_sm rsp to confirm the message received on step 31.
- SMPP client should send a deliver_sm rsp to confirm the message received on step 29.
- The ussd_map module (SCF part) processes the ussd.finalize message and sends processUnstructuredSS-Request (ResultLast).
[edit] Network initiated USSD Request
A network initiated USSD session is handled as described in the following figure:
- gsmSCF sendsunstructuredSS-Request (Invoke) to USSD Gateway (HLR part) to present a menu for MSISDN 0015559191.
- The ussd_map module (HLR part) processes the unstructuredSS-Request (Invoke) message and emits a call.route message with called=0015559191.
- After ussd_map module successfully dispatched the call.route message, it generates a ussd.execute message with callto set to the route returned in the return value of the call.route message and dispatches an ussd.execute message.
- The ysmpp module catches the ussd.execute message and if the callto param value starts with ysmppserver/ and with it it builds a deliver_sm message that it will then send to the target specified in the callto'" parameter after the ysmppserver module prefix.
- The SMPP client should send a submit_sm message towards SMPP server.
- The SMPP server processes the received submit_sm message and dispatches a call.route message.
- After successfully dispatching of call.route message the SMPP server will dispatch a call.execute message.
- The ussd_map module (SCF part) process the ussd.execute message and sends an unstructuredSS-Request (Invoke) towards the HLR.
The time to receiving a response from the user after gsmSCF has requested user interaction could be possibly quite long.
- The HLR sends unstructuredSS-Request (ResultLast) to USSD gateway
- The ussd_map module (SCF part) processes the message and emits a ussd.update message.
- ysmpp module processes the ussd.update message and sends submit_sm rsp to SMPP client to confirm the reception of the message sent on step 5.
- The SMPP client should send a deliver_sm rsp to confirm the message received on step 4.
- The ysmpp module will send a deliver_sm message to SMPP clients which will contain user's response.
- The SMPP client should send a submit_sm message to SMPP server which will contain the message received on step 13.
- The ysmpp module receives the submit_sm message and emits a ussd.update message.
- The ussd_map module (HLR part) receives the ussd.update message and sends the unstructuredSS-Request (ResultLast) to gsmSCF.
NOTE: Steps between 1 and 16 can be repeated.
- The gsmSCF sends TCAP END in order to finish the USSD session.
- The ussd_map module (HLR part) processes the TCAP END and sends a ussd.finalize message.
- The ysmpp module receives the ussd.finalize message and sends a submit_sm rsp for the message received on point 14.
- The SMPP client should send a deliver_sm rsp for the message received on point 13.
- The ysmpp module sends a deliver sm + last message indication to SMPP client.
- The SMPP client should send a submit sm + last message indication to SMPP server.
- ysmpp module sends submit_sm rsp to confirm the message received on step 22.
- SMPP client should send a deliver_sm rsp to confirm the message received on step 21.
- ysmpp module receives submit_sm message and sends a ussd.finalize message.
- The ussd_map module (SCF part) processes the ussd.finalize message and sends END.
[edit] Fallback/Proxy mode
The following images detail scenarios where the USSD GW is instructed to do failover.
The picture above details a failover scenario for when an HLR sends processUnstructuredSS-Request (Invoke) (1).
NOTES:
- The read circles in the above picture represent points in handling where a fallback decision can be made.
- A fallback decision can be made only if in all previous fallback decision points the necessity for failover was determined to be false.
- U1 and U2 represent SMPP message responses.
Decision points where ussd_map will determine the need for failover:
- E1: Routing procedure does not return a valid route (call.route returns with false or an error) or routing decision indicates a failover route (routing return a route starting with prefix ussd_map/)
- E2: ussd.execute message fails to be processed (in this case by the ysmpp module)
- E3: SMPP server received an SMPP error for deliver_sm message.
- E4: SMPP client received an SMPP error for submit_sm message.
- E5: The call.route message emitted by ysmpp does not return a valid route (call.route returns with false or an error).
- E6: ussd.execute message fails to be processed (in this case by the ussd_map module).
Network initiated USSD session fallback.
The picture above details a failover scenario for when a gsmSCF sends a "unstructuredSS-Request/unstructuredSS-Notify (Invoke) (1).
NOTES:
- The read circles in the above picture represent points in handling where a fallback decision can be made.
- A fallback decision can be made only if in all previous fallback decision points the necessity for failover was determined to be false.
- U1 and U2 represent SMPP message responses.
Decision points where ussd_map will determine the need for failover:
- E1: Routing procedure does not return a valid route (call.route returns with false or an error) or routing decision indicates a failover route (routing return a route starting with prefix ussd_map/)
- E2: ussd.execute message fails to be processed (in this case by the ysmpp module)
- E3: SMPP server received an SMPP error for deliver_sm message.
- E4: SMPP client received an SMPP error for submit_sm message.
- E5: The call.route message emitted by ysmpp does not return a valid route (call.route returns with false or an error).
- E6: ussd.execute message fails to be processed (in this case by the ussd_map module).
The SMPP USSD gateway will also be bypassed when the ussd_map module is configured to do failover for all requests.
Any type of SMPP error received either in the result for the ussd.execute or in the first message back from SMPP that does not have a mapping on MAP will lead to the ussd_map module doing failover. Errors that would generate a failover are errors like timeout, session ended abnormally, unknown errors, congestion errors.
Once ussd_map decides that failover should be done, it will use the original received message from the HLR (MO case)/gsmSCF (MT case) and it will only alter the called address to be the one of the gsmSCF/HLR set for the failover.. The calling address will remain the one received from HLR/gsmSCF, the idea being that for the first message we want to pretend that we are the original gsmSCF/HLR. When the receiving end of this message will want to respond, it will use the calling address from the message. Seeing that the ussd_map module set it to the original calller's address, further messages exchanged in that dialog between HLR and gsmSCF will not pass through USSD GW again.
[edit] Internal message API
This section documents the YATE messages used internally by the USSD GW.
[edit] call.route
This message is used by ussd_map and ysmpp module to determine a destination where a new USSD session should be sent for further processing.
This message is sent by either ussd_map module or ysmpp module when receiving a request for a new USSD session on MAP for ussd_map or on SMPP for ysmpp. ussd_map will only send this message if default routing is not enabled from configuration.
Parameters:
- id:
- type: string
- Identifier for the USSD session used by the dispatcher of the message.
- called:
- type: string
- It specifies the value on which destination is determined. For a MO USSD session, this parameter will contain the decoded USSD string (USSD request code). For a MT USSD sessions, this parameter will contain the destination MSISDN.
- callednumtype:
- type: keyword
- It specifies type (NAI) of the called parameter. It is used only when called is a MSISDN
- callednumplan:
- type: keyword
- Numbering plan for the number specified by the called parameter. It is used only when called is a MSISDN.
- caller:
- type: string:
- Identifies the caller in this USSD session. For MO USSD it can be the MSISDN (if present) . ussd_map will set the the calling party address GT in this parameter for MT case or if MSISDN is not specified for MO case.
- callernumtype:
- type: keyword
- It specifies type (NAI) of the caller parameter.
- callernumplan:
- type: keyword
- Numbering plan for the number specified by the caller parameter.
- operation_type:
- type: keyword
- The type of USSD operation that fired this message.
- text_encoding:
- type: hexified string
- The MAP USSD data coding scheme
- text_encoded:
- type: hexified string
- The encoded USSD string
- text:
- type: string
- The decoded USSD string conforming to the USSD data coding scheme.
- text.encoding:
- type: keyword
- The USSD data coding scheme.
- text.lang:
- type: keyword
- The language of the decoded text as obtained from the data coding scheme.
- text.lang_indication:
- type: boolean
- True if the language was decoded from the USSD string and not from the data coding scheme.
- imsi:
- type: string
- IMSI value if available.
- hlr:
- type: string
- It specifies the HLR GTT if that information was available.
- hlr.nature:
- type: keyword
- It specifies HLR GTT nature (NAI)
- hlr.plan:
- type: keyword
- It specifies HLR GTT numbering plan
- vlr:
- type: string
- It specifies the VLR GTT if that information was available.
- vlr.nature:
- type: keyword
- It specifies VLR GTT nature (NAI)
- vlr.plan:
- type: keyword
- It specifies VLR GTT numbering plan
- gsmscf:
- type: string
- It specifies the gsmSCF GTT if that information was available.
- gsmscf.nature:
- type: keyword
- It specifies gsmSCF GTT nature (NAI)
- gsmscf.plan:
- type: keyword
- It specifies gsmSCF GTT numbering plan
- destination_reference:
- type: string
- MSISDN or IMSI specified in the DestinationReference TCAP MAP parameter.
- destination_reference.nature:
- type: keyword
- It specifies DestinationReference nature (NAI)
- destination_reference.plan:
- type: keyword
- It specifies DestinationReference numbering plan
- msisdn:
- type: string
- MSISDN
- alert_pattern:
- type: string
- Alert Pattern parameter as received in the USSD MAP message.
- module
- type: string
- Name of the module which requested routing
- application
- type: string
- Name of the ussd_map application which sent this routing request
- route_type
- type: keyword, value: ussd
- Specifies routing type, in this case it'll be USSD routing
- smpp_session_id
- type: string
- TODO
- smpp_system_id
- type: string
- TODO
Note:
- The hlr/vlr address represents:
- the address from which the message was received (if it can be determined) for MO USSD session.
- the address where the message should be sent for MT USSD session.
Returned parameters:
- if the message was processed, the return value of the message indicates the destination of the subsequent ussd.execute message.
- if the message was not processed or it returned with error (signaled by the return value being either "-" or "error")
- ussd_map will do failover
- ysmpp will close the SMPP session, indicating an error either set by the call.route or either set to the default unknown error indication.
[edit] ussd.execute
This message is used to begin a new USSD session:
- on SMPP, if the message is directed to the ysmpp module
- on MAP if the message is directed to the ussd_map module
This message is sent by either ussd_map module or ysmpp module after successful routing stage. In case of the ussd_map module, this is message is sent if the routing stage did not indicate failover necessity.
Parameters:
- callto:
- type : string
- It specifies the target module to process the message. The string should start with 'ysmppserver/' for the ysmpp" module and with ussd_map/ for the ussd_map module.
- id:
- type: string
- Identifier for the USSD session used by the dispatcher of the message.
- called:
- type: string
- It specifies the value on which destination is determined. For a MO USSD session, this parameter will contain the decoded USSD string (USSD request code). For a MT USSD sessions, this parameter will contain the destination MSISDN.
- callednumtype:
- type: keyword
- It specifies type (NAI) of the called parameter. It is used only when called is a MSISDN
- callednumplan:
- type: keyword
- Numbering plan for the number specified by the called parameter. It is used only when called is a MSISDN.
- caller:
- type: string:
- Identifies the caller in this USSD session. For MO USSD it can be the MSISDN (if present) . ussd_map will set the the calling party address GT in this parameter for MT case or if MSISDN is not specified for MO case.
- callernumtype:
- type: keyword
- It specifies type (NAI) of the caller parameter.
- callernumplan:
- type: keyword
- Numbering plan for the number specified by the caller parameter.
- operation_type:
- type: keyword
- The type of USSD operation that fired this message.
- text_encoding:
- type: hexified string
- The MAP USSD data coding scheme
- text_encoded:
- type: hexified string
- The encoded USSD string
- NOTE: If YATE uses in the internal messages the decoded text, this parameter should not be set (it has higher priority in ussd_map).
- text:
- type: string
- The decoded USSD string conforming to the USSD data coding scheme.
- text.encoding:
- type: keyword
- The USSD data coding scheme.
- text.lang:
- type: keyword
- The language of the decoded text as obtained from the data coding scheme on MAP or from language indicator on SMPP.
- text.lang_indication:
- type: boolean
- True if the language was decoded from the USSD string and not from the data coding scheme or if should be encoded on MAP in the USSD string payload.
- Set to false for UCS2 encoding without language indication
- imsi:
- type: string
- IMSI value if available.
- hlr:
- type: string
- It specifies the HLR GTT if that information was available.
- hlr.nature:
- type: keyword
- It specifies HLR GTT nature (NAI)
- hlr.plan:
- type: keyword
- It specifies HLR GTT numbering plan
- vlr:
- type: string
- It specifies the VLR GTT if that information was available.
- vlr.nature:
- type: keyword
- It specifies VLR GTT nature (NAI)
- vlr.plan:
- type: keyword
- It specifies VLR GTT numbering plan
- gsmscf:
- type: string
- It specifies the gsmSCF GTT if that information was available.
- gsmscf.nature:
- type: keyword
- It specifies gsmSCF GTT nature (NAI)
- gsmscf.plan:
- type: keyword
- It specifies gsmSCF GTT numbering plan
- destination_reference:
- type: string
- MSISDN or IMSI specified in the DestinationReference TCAP MAP parameter.
- destination_reference.nature:
- type: keyword
- It specifies DestinationReference nature (NAI)
- destination_reference.plan:
- type: keyword
- It specifies DestinationReference numbering plan
- msisdn:
- type: string
- MSISDN
- alert_pattern:
- type: string
- Alert Pattern parameter as received in the USSD MAP message.
Note:
- The hlr/vlr address represents:
- the address from which the message was received (if it can be determined) for MO USSD session.
- the address where the message should be sent for MT USSD session.
Returned parameters:
- peerid:
- type: string
- Identifier assigned for this USSD session by the entity that processed this message.
- error:
- type: keyword
- Error returned if the message was not processed.
Processing of this message will return failure:
- if the message will not be processed
- if the 'id' parameter is missing.
- in case of processing error
- in case of congestion
[edit] ussd.update
This message is used for transmitting USSD messages during a USSD session. This type of message will be used after the initial stage of creating the session through ussd.execute has succeeded.
When receiving this message:
- the ussd_map module will generate a TCAP CONTINUE message
- the ysmpp module will generate a SMPP deliver_sm if it acts as a server (as in the case of the USSD GW) or submit_sm if it acts as a SMPP client.
Parameters:
- id:
- type: string
- USSD session identifier of the sending side of the message
- peerid:
- type: string
- USSD session identifier for the module that should process this message
- operation_type:
- type: keyword
- The type of operation that fired this message.
- text_encoding:
- type: hexified string
- The MAP USSD data coding scheme
- text_encoded:
- type: hexified string
- The encoded USSD string
- NOTE: If YATE uses in the internal messages the decoded text, this parameter should not be set (it has higher priority in ussd_map).
- text:
- type: string
- The decoded USSD string conforming to the USSD data coding scheme.
- text.encoding:
- type: keyword
- The USSD data coding scheme.
- text.lang:
- type: keyword
- The language of the decoded text as obtained from the data coding scheme on MAP or from language indicator on SMPP.
- text.lang_indication:
- type: boolean
- True if the language was decoded from the USSD string and not from the data coding scheme or if should be encoded on MAP in the USSD string payload.
- Set to false for UCS2 encoding without language indication
- error:
- type: keyword
- Error received from one the USSD session endpoints. It might be a MAP error when HLR/gsmSCF/ failed to process a request or SMPP error when the SMPP client failed to process a request.
Returned parameters:
- error:
- type: keyword
- Error code if this message failed to be processed.
Points of failure:
- The USSD session specified by peerid parameter cannot be found by the processing side.
- Processing of this message will be refused if it is received after a ussd.finalize message.
- Processing of this message will return an error if there are mandatory parameters missing of if the parameters specify a values not allowed in the context of the USSD session (e.g., sending a processUnstructuredSS-Request inside a ussd.update message)
[edit] ussd.finalize
This message is used to signal the termination of the USSD session. Successful processing of this message means that the USSD session was terminated and is no longer available.
When receiving this message:
- the ussd_map module will generate a TCAP END/ABORT message depending upon the parameters received. A message containing an error that does not map to a MAP error will generate a TCAP ABORT.
- the ysmpp module will generate a SMPP deliver_sm if it acts as a server (as in the case of the USSD GW) or submit_sm if it acts as a SMPP client, a message that will usually contain a last message indication.
Parameters:
- id:
- type: string
- USSD session identifier of the sending side of the message
- peerid:
- type: string
- USSD session identifier for the module that should process this message
- operation_type:
- type: keyword
- The type of operation that fired this message.
- text_encoding:
- type: hexified string
- The MAP USSD data coding scheme
- text_encoded:
- type: hexified string
- NOTE: If YATE uses in the internal messages the decoded text, this parameter should not be set (it has higher priority in ussd_map).
- The encoded USSD string
- text:
- type: string
- The decoded USSD string conforming to the USSD data coding scheme.
- text.encoding:
- type: keyword
- The USSD data coding scheme.
- text.lang:
- type: keyword
- The language of the decoded text as obtained from the data coding scheme on MAP or from language indicator on SMPP.
- text.lang_indication:
- type: boolean
- True if the language was decoded from the USSD string and not from the data coding scheme or if should be encoded on MAP in the USSD string payload.
- Set to false for UCS2 encoding without language indication
- error:
- type: keyword
- Error received from one the USSD session endpoints. It might be a MAP error when HLR/gsmSCF/ failed to process a request or SMPP error when the SMPP client failed to process a request.
Returned parameters:
- error:
- type: keyword
- Error code if this message failed to be processed.
Points of failure:
- The USSD session specified by 'peerid parameter cannot be found by the processing side.
- Processing of this message will return an error if there are mandatory parameters missing of if the parameters specify a value not allowed in the context of the USSD session
[edit] Keyword values
This section details acceptable values for parameters listed as having type keyword.
- hlr.nature/vlr.nature/gsmscf.nature/destination_reference.nature
- unknown
- international
- national
- network-specific
- subscriber
- abbreviated
- hlr.plan/vlr.plan/gsmscf.plan/destination_reference.plan
- unknown
- isdn
- data
- telex
- land-mobile
- national
- private
- operation_type
- pssd: mapping of MAP v1 USSD operation processUnstructuredSS-Data and of SMPP operation PSSD.
- pssr: mapping of MAP v2 USSD operation processUnstructuredSS-Request and of SMPP operation PSSR.
- ussr: mapping of MAP v2 USSD operation unstructuredSS-Request and of SMPP operation USSR".
- ussn: mapping of MAP v2 USSD operation unstructuredSS-Notify and of SMPP operation USSN.
- error
- invalid_logic: error reported when required processing does not follow USSD rules (e.g., MT request starting with processUnstructuredSS-Requests)
- system_failure: error mapping for MAP error systemFailure.
- data_missing: error mapping for MAP error dataMissing.
- unexpected_data: error mapping for MAP error unexpectedDataValue.
- unknown_alphabet: error mapping for MAP error unknownAlphabet.
- absent_subscriber: error mapping for MAP error absentSubscriber.
- illegal_subscriber: error mapping for MAP error illegalSubscriber.
- illegal_equipment: error mapping for MAP error illegalEquipment.
- ussd_busy: error mapping for MAP error ussd-Busy.
- call_barred: error mapping for MAP error callBarred.
- network_failure: error signaling message transmission failure due to connectivity issues either on the SS7 side or SMPP side.
- timeout_expired: error signaling a request timeout occurrence.
- ussd_sess_end_abnormally: error signaling USSD session termination due to an unknown cause. Mapping for this error implies a TCAP Abort either being generated of received.
- unknown_error: error specified when there is no available mapping for an errror from SMPP to MAP or vice versa.
- throttling_error: error signaling that a message failed to be processed due to processing side being in congestion state.
- protocol_error: SMPP generic error. This error is put whenever there is a SMPP specific error that cannot be mapped into one of the other errors.
- node
- MAP parameter for when error = system_failure
- maps to networkResource in the MAP Error.
- possible values are: plmn, hlr, vlr, pvlr, controllingMSC, vmsc, eir, rss. Defaults to plmn if not given
- cause
- MAP parameter for when error = call_barred
- maps to callBarringCause in the MAP Error
- possible values are: barringServiceActive, operatorBarring. Defaults to operatorBarring if not given
- text.encoding
- gsm7bit / GSM7Bit: text was encoded/is to be encoded GSM 7 Bit
- ucs2 / UCS2: text was encoded/is to be encoded UCS 2
- text.lang
- two character string specifying a language according to ISO 639-1 or integer value if mapping is not provided.
[edit] SMPP custom parameters
- 0x1502 => IMSI;
- 0x1503 => VLR Type of Number;
- 0x1504 => VLR Numbering Plan Indicator;
- 0x1505 => VLR address;
- 0x1506 => GSM SCF Type of Number;
- 0x1507 => GSM SCF Numbering Plan Indicator;
- 0x1508 => GSM_SCF address;
- 0x1509 => Destination Reference Type of Number;
- 0x150a => Destination Reference Numbering Plan Indicator;
- 0x150b => Destination Reference;
- 0x150c => MSISDN
- 0x150d => Alerting Pattern
- 0x1800 => HLR Type of Number;
- 0x1801 => HLR Numbering Plan Indicator;
- 0x1802 => HLR address.
[edit] Configuration
[edit] ysigchan module
In order to have MAP connectivity, TCAP instances must be configured in ysigchan.conf:
; Example of a SS7 Transaction Capabilities Application Part ; This component is created when encountering a section of this kind ;[ss7tcap] ; type: keyword: identifies the component as a SS7 Transfer Capabilities Application Part ; type = ss7-tcap-ansi for ANSI TCAP ; type = ss7-tcap-itu for ITU TCAP ;type= ; local_SSN: local SubSystem Number. Mandatory ;local_SSN= ; default_remote_SSN: remote SubSystem Number to provide to SCCP if the application does not provide one ;default_remote_SSN= ; default_remote_pointcode: remote Point Code to provide to SCCP if the application does not provide one ;default_remote_pointcode= ; pointcodetype: remote Point Code type. See above documentation for available types ;pointcodetype= ; sccp: Name of the SCCP component to create and be used by this TCAP ; A section with the name given here must exist in order to configure the SCCP level ;sccp= ; default_hopcounter: HopCounter provided to SCCP if the application does not provide one ; Values range 1-15, 0 or boolean false disables, boolean true sets to 15 ; A non-zero value will force using XUDT or LUDT instead of UDT messages ;default_hopcounter=false ; transact_timeout: Time in seconds to timeout a TCAP transaction after no more activity was registered on it ; NOTE: Values below 15 seconds will be ignored and the timer will assume the default value. ; Defaults to 300 seconds ;transact_timeout=300 ; max_timeout_checks: integer: Maximum number of timeout checks done on a transaction without starting the transaction ; timer before forcefully starting the transaction timer ; Defaults to 10 ;max_timeout_checks=10 ; timeout_check: Time interval in milliseconds to check for timeouts. ; Default to 100 ms ;timeout_check=100 ; floodevents: int: How many queued incoming TCAP messages trigger a congestion warning and the drop mechanism ; for Unidirectional/Begin/QueryWithPermission/QueryWithoutPermission messages. ; Exit from congestion will take place when there are less the floodevents/4 messages in the queue ; NOTE! Setting this parameter to 0 will disable the congestion warning and protection. Setting it to one will ; be overriden and floodevents will be set to 2. ;floodevents=1000 ;print-messages: Boolean to enable/disable printing of decoding/encoding of TCAP messages ; This option applies on reload ;print-messages=false ;extended-debug: Boolean to enable/disable printing of the step-by-step decoding/encoding of TCAP messages ; This option applies on reload. print-messages must be true. ;extended-debug=false ; hash_list_size: integer: Size of HashList used for keeping the list of current transactions ;hash_list_size=17
Configuration Example
[tcap-scf]
;enable=no
type=ss7-tcap-itu
sccp=sccp
local_SSN=147
pointcodetype=ITU
print-messages=false
extended-debug=false
transact_timeout=600
floodevents=1000
[tcap-hlr]
;enable=no
type=ss7-tcap-itu
sccp=sccp
local_SSN=7
pointcodetype=ITU
print-messages=false
extended-debug=false
transact_timeout=600
Further configuration for SS7 connectivity is required (SCCP, MTP3, etc.).
[edit] camel_map module
NOTE: As of SVN revision 1285, there is a new camelmap module. For compatibility reasons, the old module, camel_map, was also kept. Both modules read the same configuration file, camel_map.conf. In order to avoid issues, please make sure to only enable one of these modules in the [postload] section of yate.conf.
The new module is the one that offers USSD UCS2 encoding without language indication, but beware that TCP functionality has been removed from it. That functionality has been moved to the xml_tcp module. The module only uses messages to communicate with applications. ussd_map uses messages, so there should be no need for TCP functionality.
Configuring of tracking IDs is done in the general section:
[general] ;track_id: string: Shared engine variable name used to obtain a unique tracking ID for TCAP transactions ; If not set, the module will not set a tracking ID for the TCAP transaction ;track_id= ;track_id_base: string: Optional string with which to prefix the tracking ID ; This setting has no effect if track_id is not set ;track_id_base=
In order to allow communication over MAP through SS7, sections configurating application should exist for each role of the ussd_map module (gsmSCF/HLR). A camel_map.conf section configuring an application looks like this:
;[local appName] ; This section configures a local application which transmits the XML messages as internal Yate messages ; translator: string: name of translator to be used by this application. ; Must be one one the [tcap ...] sections configured in the camel_map.conf file. ;translator= ; capabilities: string: List of capabilities separated by commas which this application supports ;capabilities= ; export_xml_as: string: Specify in which way the XML will be passed along into a Yate message ; Allowed values are: ; - string: pass the XML as a string ; - object: pass the XML as an object ; - both: pass the XML as a string and object ;export_xml_as=object ; enable: bool: Enable this application ;enable=yes
The translator setting refers to a section of the type defined below which configures atachement to a TCAP instance
;[tcap map] ; This section configures a TCAP User MAP/CAMEL protocol translator ; enable: bool: Enable this translator ;enable=yes ; type: string: Type of TCAP User ; Allowed values are MAP or CAMEL ;type=MAP ; host: IP address: Address on which the TCP listener should bind on for XML communication ;host=127.0.0.1 ; port: integer: Port on which the TCP listener should bind on for XML communication ; Note: setting port to 0 will disable the listener, so it will not accept TCP applications ;port=5555 ; tcap: string: Name of TCAP to which this TCAP user should attach itself to for the SS7 communication ;tcap= ; add-encoding: bool: Always add encoding attribute to XML elements for decoded parameters ;add-encoding=default from [general] ; add-timestamp: bool: Add to XML timestamps used for estimating application latency ;add-timestamp=default from [general] ; print-messages: bool: Debug option to print TCAP and XML messages. This option is applicable on reload. ;print-messages=false ; ussd-string: string: Specifies what the ussd-String parameter will contain as data ; Allowed values are: ; - octets: ussd-String will contain the octets as they were received ; - text: ussd-String will contain the GSM7Bit decoded text ; This can be overriden in application sections ;ussd-string=text ; ussd-decode: string: Specifies what ussd-String parameters should be decoded into text ; Allowed values are: ; - none: ussd-String parameters will never be decoded into text ; - first: ussd-String in a TCAP Begin message will be decoded into text ; - all: all ussd-String parameters will be decoded into text ; This can be overriden in application sections ;ussd-decode=all ; hash_list_size: integer: Size of HashList used for mapping of TCAP transactions to applications ;hash_list_size=17
For load sharing (especially in cases of high loads), you can configure multiple applications using the same translator.
Configuration Example
The example below configures 2 applications acting as a gsmSCF, each one attached to the TCAP instance with gsmSCF SSN, and 2 applications as HLR, each one attached to the TCAP instance with HLR SSN 6:
[general]
track_id=ussdgw
track_id_base=ussdgw/
[tcap scf]
;enable=no
tcap=tcap-scf
host=0.0.0.0
port=0
type=MAP
print-messages=false
add-encoding=false
[tcap hlr]
;enable=no
tcap=tcap-hlr
host=0.0.0.0
port=0
type=MAP
print-messages=false
add-encoding=false
[local ussdscf1]
translator=scf
capabilities=USSD
export_xml_as=object
ussd-string=octets
ussd-decode=all
[local ussdscf2]
translator=scf
capabilities=USSD
export_xml_as=object
ussd-string=octets
ussd-decode=all
[local ussdhlr1]
translator=hlr
capabilities=USSD
export_xml_as=object
ussd-string=octets
ussd-decode=all
[local ussdhlr2]
translator=hlr
capabilities=USSD
export_xml_as=object
ussd-string=octets
ussd-decode=all
Note If SMPP is configured to expect decoded USSD texts (which is the default configuration), the ussd-decode configuration setting should be set to all.
[edit] ussd_map module
The module is configured through ussd_map.conf. The configuration file sets timeout parameters and processing threads parameters in the general section:
[general] ; hash_list_size: integer: Size of HashList for keeping dialogs ;hash_list_size=17 ; component_ttl: integer: Component time to live in milliseconds ; Minimum allowed value is 1000 ; Defaults to 600000 (10 minutes) ;component_ttl=600000 ; dialog_idle_ttl: integer: Dialog idle (nothing sent/received) time to live in milliseconds ; Minimum allowed value is 1000 ; It can be set to 0 to keep it alive until the remote party terminates the dialog ; Defaults to 86400000 (1 day) ;dialog_idle_ttl=86400000
; dialog_ended_ttl: integer: Ended dialog time to live in milliseconds ; Minimum allowed value is 1000. ; It can be set to 0 to remove the dialog after termination ; Defaults to 0 ;dialog_ended_ttl=0 ; dispatcher_maxthreads: integer: Maximum number of message dispatch threads to use ; Minimum value is 1 for use of dispatching threads. ; NOTE: if the value is set to 0, the module will enqueue the messages into YATE's engine. ;dispatcher_maxthreads=0
; dispatcher_minthreads: integer: Minimum number of message dispatch threads to use ; Minimum value is 1 for use of dispatching threads. ;dispatcher_minthreads=1
;dispatcher_priority: string: Default priority of message dispatch threads ;dispatcher_priority=normal
; floodevents: integer: Threshold for signaling congestion when the number of messages waiting to be dispatched exceeds it. ; When entering congestion, all new MAP dialogs and USSD sessions will be refused. ; 0 disables the mechanism ;floodevents=0
; congestion_exit_factor: double: Factor used to calculate the exit congestion threshold ; NOTE: if the factor results in a exit congestion threshold of 0 or greater than floodevents, ; the setting will be overriden and the exit congestion threshold will be set to 1. ;congestion_exit_factor=0.5
Timeout settings should be correlated with timeout settings in TCAP and SMPP, each having its own timeout mechanism.
Gateway applications which do the MAP <-> USSD translation are configured through section like the one below:
[appName] ; section name is the name of the camel_map application, it must correspond to a [local appName] section in camel_map
; enable: boolean: Enable this application ; Defaults to yes ;enable=yes ; type: string: Type of MAP <-> USSD translator: ; - SCF means that is the part that receives new dialogs from the HLR (user initiated USSD) ; - HLR is the part that receives new dialogs from gsmSCF (network initiated USSD) ; This setting cannot be changed on reload. ;type= ; export_xml_as: string: Specify in which way the XML will be passed along into ;export_xml_as=object ; print_msg: boolean: Print sent/received messages to output ;print_msg=no ; print_xml: boolean: Print sent/received XML data to output ;print_xml=no ; local_addr. : prefix: Parameters prefixed with this set the local SCCP address of this application ; Meaningful values are: ; local_addr.CallingPartyAddress.route= ; local_addr.CallingPartyAddress.ssn= ; local_addr.CallingPartyAddress.pointcode= ; local_addr.CallingPartyAddress.gt= ; local_addr.CallingPartyAddress.gt.nature= ; local_addr.CallingPartyAddress.gt.plan= ; local_addr.CallingPartyAddress.gt.translation= ; local_addr.CallingPartyAddress.gt.encoding= ; default_routing: bool : Do routing to default address for all messages ; default_routing=no ; default_addr. : prefix: parameters prefixed with this will be used as the default SCCP called address ; Meaningful values are: ; default_addr.application= ; default_addr.CalledPartyAddress.route= ; default_addr.CalledPartyAddress.ssn= ; default_addr.CalledPartyAddress.pointcode= ; default_addr.CalledPartyAddress.gt= ; default_addr.CalledPartyAddress.gt.nature= ; default_addr.CalledPartyAddress.gt.translation= ; default_addr.CalledPartyAddress.gt.encoding= ; hlr_ssn: integer: The SSN expected in the calling address from a HLR. ; This setting has significance only for SCF type applications ;hlr_ssn=6 ; vlr_ssn: integer: The SSN expected in the calling address from a VLR. ; This setting has significance only for SCF type applications ;vlr_ssn=7
Each section should have its own equivalent in camel_map.conf.
In the USSD GW scenario, at least tho applications are needed, one acting as SCF, one as HLR. For load sharing multiple gsmSCF and HLR applications can be configured (see the configuration example below).
Configuration Example
The example below configures 2 gsmSCF applications and 2 HLR applications, each one corresponding with a application section in the camel_map.conf example:
[general]
component_ttl=600000
dialog_ended_ttl=0
dispatcher_maxthreads=10
dispatcher_minthreads=5
;dispatcher_priority=normal
floodevents=1000
[ussdscf1]
;enable=no
type=SCF
export_xml_as=object
print_msg=no
print_xml=no
local_addr.CallingPartyAddress.route=gt
local_addr.CallingPartyAddress.gt=8828723
local_addr.CallingPartyAddress.gt.nature=international
local_addr.CallingPartyAddress.gt.plan=isdn
local_addr.CallingPartyAddress.gt.translation=0
local_addr.CallingPartyAddress.gt.encoding=bcd
default_routing=no
default_addr.application=ussdHLR
default_addr.CalledPartyAddress.route=gt
default_addr.CalledPartyAddress.gt=8820723
default_addr.CalledPartyAddress.gt.nature=international
default_addr.CalledPartyAddress.gt.plan=isdn
default_addr.CalledPartyAddress.gt.translation=0
default_addr.CalledPartyAddress.gt.encoding=bcd
[ussdscf2]
;enable=no
type=SCF
export_xml_as=object
print_msg=no
print_xml=no
local_addr.CallingPartyAddress.route=gt
local_addr.CallingPartyAddress.gt=8828723
local_addr.CallingPartyAddress.gt.nature=international
local_addr.CallingPartyAddress.gt.plan=isdn
local_addr.CallingPartyAddress.gt.translation=0
local_addr.CallingPartyAddress.gt.encoding=bcd
default_routing=no
default_addr.application=ussdHLR
default_addr.CalledPartyAddress.route=gt
default_addr.CalledPartyAddress.gt=8820723
default_addr.CalledPartyAddress.gt.nature=international
default_addr.CalledPartyAddress.gt.plan=isdn
default_addr.CalledPartyAddress.gt.translation=0
default_addr.CalledPartyAddress.gt.encoding=bcd
[ussdhlr1]
;enable=no
type=HLR
print_msg=no
print_xml=no
export_xml_as=object
local_addr.CallingPartyAddress.route=gt
local_addr.CallingPartyAddress.gt=8828723
local_addr.CallingPartyAddress.gt.nature=international
local_addr.CallingPartyAddress.gt.plan=isdn
local_addr.CallingPartyAddress.gt.translation=0
local_addr.CallingPartyAddress.gt.encoding=bcd
default_routing=no
default_addr.application=ussdSCF
default_addr.CalledPartyAddress.route=gt
default_addr.CalledPartyAddress.gt=8820457
default_addr.CalledPartyAddress.gt.nature=international
default_addr.CalledPartyAddress.gt.plan=isdn
default_addr.CalledPartyAddress.gt.translation=0
default_addr.CalledPartyAddress.gt.encoding=bcd
[ussdhlr2]
;enable=no
type=HLR
print_msg=no
print_xml=no
export_xml_as=object
local_addr.CallingPartyAddress.route=gt
local_addr.CallingPartyAddress.gt=8828723
local_addr.CallingPartyAddress.gt.nature=international
local_addr.CallingPartyAddress.gt.plan=isdn
local_addr.CallingPartyAddress.gt.translation=0
local_addr.CallingPartyAddress.gt.encoding=bcd
default_routing=no
default_addr.application=ussdSCF
default_addr.CalledPartyAddress.route=gt
default_addr.CalledPartyAddress.gt=8820457
default_addr.CalledPartyAddress.gt.nature=international
default_addr.CalledPartyAddress.gt.plan=isdn
default_addr.CalledPartyAddress.gt.translation=0
default_addr.CalledPartyAddress.gt.encoding=bcd
[edit] ysmpp module
TODO - configuration explanations
NOTE The module encodes text to ASCII for default encoding (configuration parameter default_encoding_type). If you want to send GSM 7 Bit for SMPP default encoding, please see how the setting is set below.
Configuration Example'
[general]
server=smpp-server
track_id=ussdgw
track_id_base=ussdgw/
[smpp-server]
enable=true
session_responseinterval=600000
sessionset_process_max=1
codec_warndefaults=false
print-messages=no
[listenerserver server]
;enable=yes
addr=0.0.0.0
port=12345
; use GSM 7 Bit for default SMPP encoding
default_encoding_type=gsm7bit
[edit] Monitoring
This section details comands through which the state of the USSD GW can be monitored.
[edit] ussd_map module
- Congestion state monitoring
The ussd_map module will generate an alarm when entering/exiting a congestion state. If SNMP support is enabled, this will generate a trap on SNMP. The congestion status is also reported in the state entry in the result of the module status command.
- Module status
The module reports its status through the following command in the YATE telnet console:
status ussd_map
The command will print the following information:
workers=count_of_dispatching_threads,messages=count_msg,dialogs=count_of_dialogs,state=normal,count=count_of_applications;format=Type | CurrentDlgs| MAPCreated | UssdCreated |DefaultRouted | MAPSent | MapRecv | USSDSent | USSDRecv | MAPAbort | USSDAbort | BuiltAbort | MAPTimeouts | USSDTimeouts
where:
- workers: current number of used dispatching threads from the maximum configured pool (e.g., 3/10 means 3 threads are used of a pool of 10)
- messages: count of messages waiting on the dispatching queue of the engine
- dialogs: total number of USSD sessions currently handled by all applications
- state of the engine: normal/congestion
- count: number of applications acting either as gsmSCF, either as HLR
- format: name of the application for which the following data is reported:
- Type: role of the application: SCF (communicates with real HLR), HLR (communicates with real gsmSCF)
- CurrentDlgs: number of current MAP dialogs handled by this application
- MAPCreated: number of sessions (dialogs) started by the MAP side
- UssdCreated: number of sessions (dialogs) started by the SMPP side
- DefaultRouted: number of dialogs for which failover took place
- MAPSent: number of MAP messages sent to gsmSCF/HLR. It doesn't count the ones sent via failover routing.
- MAPRecv: number of MAP messages received from gsmSCF/HLR
- USSDSent: number of sent ussd.execute/ussd.update/ussd.finalize messages towards the SMPP side.
- USSDRecv: number of received ussd.execute/ussd.update/usdd.notify messages from SMPP side.
- MAPAbort: number of dialog aborts generated by MAP side
- USSDAbort: number of dialog aborts generated by USSD side
- BuiltAbort: number of dialog aborts generated by the ussd_map module (e.g., not having a ussd.update message processed by anyone will cause ussd_map to generate session abort)
- MAPTimeouts: number of dialog timeouts generated by MAP side
- USSDTimeouts: number of timeouts reported by USSD side
- Module control commands
The module offers the following control commands through the telnet console:
- control ussd_map appName print-msg [yes|no|verbose] : enable printing of received/sent map./ussd./messages.
- control ussd_map appName print-xml [yes|no|verbose] : enable printing of received/sent XMLs.
- control ussd_map appName export-xml-as [string|object|both] : change the way XML is set in the internal messages
- control ussd_map start_stats : begin gathering data for statistics
- control ussd_map stop_stats : stop gathering data for statistics
- control usdd_map stats : print statistic data per engine and each application in part. Data contains number of MAP messages handled per second, number of USSD messages handled per second, maximum number of current dialogs, number of timeouts and number of aborts.
[edit] ysmpp module
The ysmpp module provides the following options for status command:
'NOTE' the module_name can take the following values: smppserver or smppclient.
- status module_name listeners
Prints the module listeners status in format: Address|Status|Reason.
- status module_name sessions
Prints the status of the sessions in format: Id|State|BindMode|SystemId|IpAddress:Port|Congested|Incoming Queue|Outgoing Queue;
- Id: The ID of the SMPP session. Can be used for routing.
- State: The state of the SMPP session.
- BindMode: The mode in which the session was bound. (Send/Recv/SendRecv)
- SystemId: The id with which the session has been authenticated. Can be used in routing.
- IpAddress:Port: The Ip Address and port of the remote end of the session.
- Congested: True if this session is in congestion state.
- Incoming Queue: The number of messages not processed in the incoming queue.
- Outgoing Queue: The number of messages not processed in the outgoing queue.
- status module_name ussd overview
Prints the stats of the USSD sessions in format: Total|Active|Average Duration|Total Sent|Total Received|AverageTrafficPerSecond|EndedWithErrors|CongestionRefused
- Total: the number of USSD sessions created since the starting of the program.
- Active: the number of USSD sessions currently active.
- Average Duration: average duration of a ussd session.
- Total Sent: total number of SMPP messages sent for USSD sessions.
- Total Received: total number of SMPP messages received for USSD sessions.
- AverageTrafficPerSecond: average traffic per second for USSD sessions.
- EndedWithErrors: the number of USSD sessions that ended with error.
- CongestionRefused: the number of USSD sessions refused because the server was overloaded.
[edit] References
- Mobile Application Part (MAP) specification: ETSI TE 129 002
