Ybts module

Description
The module implements a BTS.

Abbreviations:
 * MT - Mobile Terminated
 * MO - Mobile Originated
 * SMS - Short Message Service
 * USSD - Unstructured Supplementary Service Data
 * UE - User Equipment
 * IMSI - International Mobile Subscriber Identity (SIM card identifier)
 * IMEI - International Mobile Station Equipment Identity (phone identifier)
 * TMSI - Temporary Mobile Subscriber Identity (temporary identity associated by the BTS to an IMSI)
 * MSISDN - Mobile Subscriber Integrated Services Digital Network-Number (subscriber phone number)

The examples below will use the following UE data: IMSI: 001900000000001 TMSI: 00000001 IMEI: 123456789012345 MSISDN: 100

Location Updating / IMSI Detach
UE Location Updating is done using the user.register message. UE IMSI Detach (unregister) is done using the user.unregister message. Both messagess will have the following parameters:
 * driver: Module name (ybts)
 * username: UE IMSI
 * imei: UE IMEI if available
 * tmsi: UE TMSI
 * msisdn: UE MSISDN if available

A module handling the user.register message may return UE MSISDN in the msisdn parameter.

Voice calls
The module can handle MT/MO voice calls. Only one call is allowed for an UE. E.g. once a call is started (MO or MT) any subsequent call setup will be denied.

Routing MT Calls
MT calls can be routed to ybts module using its prefix (ybts/) followed by MSISDN, IMSI, TMSI or IMEI. If MSISDN is used it must be prefixed by a '+' character.

Javascript example:

var m = new Message("call.execute"); m.callto = "ybts/+100"; m.callto = "ybts/IMSI001900000000001"; m.callto = "ybts/TMSI00000001"; m.callto = "ybts/IMEI123456789012345";

Regexroute example:

[default] ^100$=ybts/+100 ^100$=ybts/IMSI001900000000001 ^100$=ybts/TMSI00000001 ^100$=ybts/IMEI123456789012345

Routing MO Calls
When handling a call setup request from UE the module will fill the following parameters in call.preroute message:
 * caller: This parameter is filled with available information in the following order: MSISDN, IMSI, TMSI. E.g. if MSISDN is available caller will be +100; if MSISDN is not available and UE IMSI is available caller will be IMSI001900000000001
 * called: Called number as received from phone
 * username: UE IMSI. E.g. username=001900000000001
 * imei: UE IMEI. E.g. imei=123456789012345
 * privacy: True if UE requested privacy

MT SMS
The module handles MT SMS delivered in msg.execute message. The target can be specified in callto parameter in the same way as for MT voice calls. The message may contain a maxpdd parameter with allowed interval (in milliseconds) for the SMS to start. E.g. this is the interval to wait for UE to respond to paging request if paging needs to be done.

There are 2 ways to specify SMS content: 1. The message may contain an rpdu parameter which is a hexified buffer with the SMS packet content. 2. The message may contain a text parameter with SMS plain text data. This will be used to build a GSM 7 bit encoded SMS deliver to be sent to UE.

The message handler will wait in a loop for the SMS to be delivered. It will return true on success, false on failure. Failure means the module failed to deliver the SMS (e.g. timeout) or the UE returned error.

MO SMS
The module will route MO SMS. The call.route message have the following parameters:
 * caller: Same as MO voice calls
 * route_type: msg
 * called: SMSC number
 * sms.called: SMS destination phone number, may not be present
 * text: SMS text if decoded (the module can decode GSM 7 bit encoded SMS data)
 * rpdu: Hexified buffer containing the SMS packet as received from UE

If route succeeds the module will dispatch a msg.execute message.

USSD
NOTE: The module don't implement any USSD encoding. It needs another module to implement handlers for map.encode and map.decode messages.

MT USSD
MT USSD is started when handling ussd.execute messages. Here are expected message parameters:
 * callto: USSD target. Specified in the same way as for MT voice calls
 * operation_type: ussr (USSD request) or ussn (USSD notify)
 * text: USSD text
 * text.: Extra text attributtes
 * id: Optional sender session id

For operation_type=ussr the module will dispatch a map.encode message with the following xml:

  Some text 

A module handling the message must return encoded data in data parameter. YBTS will start an USSD session with the UE if encode succeeds. The module will set a peerid (with YBTS session id) parameter in the ussd.execute message on return.

MO USSD
The module will start a MO USSD when receiving a SS register from UE containing an USSD request. After succesfully decoding received data (using a map.decode with data parameter) message the module will dispatch a call.route message with the following parameters:
 * route_type: ussd
 * caller: Same as MO voice calls
 * called: Decoded USSD text
 * operation_type: pssr
 * text: Decoded USSD text
 * text.: Extra text attributtes
 * id: YBTS generated session id

Here is an example of expected result from map.decode:   *8773# 

If call.route succeeds the module will dispatch an ussd.execute using returned target. The USSD session will be started if ussd.execute succeeds. The module will remember peer's id from ussd.execute message.

Subsequent messages
There are 2 messages used for session management:
 * ussd.update: Forward USSD request/notify/error to/from UE
 * ussd.finalize: Terminate the session

Both messages must have the following parameters:
 * id: Sender session id
 * peerid: Destination session id

USSD content parameters (operation_type and text) MUST be present when updating a session and MAY be present when terminating one.

Related topics

 * Communication protocols
 * Authentication and authorization procedures