[[mncc]] == MNCC for External Call Control The 3GPP GSM specifications define an interface point (service access point) inside the MSC between the call-control part and the rest of the system. This service access point is called the MNCC-SAP. It is described in _3GPP TS 24.007_ <<3gpp-ts-24-007>> Chapter 7.1. However, like for all internal interfaces, 3GPP does not give any specific encoding for the primitives passed at this SAP. The MNCC protocol has been created by the Osmocom community and allows to control the call handling and audio processing by an external application. The interface is currently exposed using Unix Domain Sockets. The protocol is defined in the `mncc.h` header file. It is exposed by the Osmocom MSC layer (both in the old OsmoNITB as well as the new OsmoMSC. {program-name} can run in two different modes: . with internal MNCC handler . with external MNCC handler === Internal MNCC handler When the internal MNCC handler is enabled, {program-name} will switch voice calls between GSM subscribers internally and automatically based on the the subscribers _extension_ number. No external software is required. NOTE: Internal MNCC is the default behavior. ==== Internal MNCC Configuration The internal MNCC handler offers some configuration parameters under the `mncc-int` VTY configuration node. ===== `default-codec tch-f (fr|efr|amr)` Using this command, you can configure the default voice codec to be used by voice calls on TCH/F channels. ===== `default-codec tch-h (hr|amr)` Using this command, you can configure the default voice codec to be used by voice calls on TCH/H channels. [[mncc-external]] === External MNCC handler When the external MNCC handler is enabled, {program-name} will not perform any internal call switching, but delegate all call-control handling towards the external MNCC program connected via the MNCC socket. If you intend to operate {program-name} with external MNCC handler, you have to start it with the `-m` or `--mncc-sock` command line option. At the time of this writing, the only external application implementing the MNCC interface compatible with the Osmocom MNCC socket is `lcr`, the Linux Call Router. More widespread integration of external call routing is available via the OsmoSIPConnector. === DTMF considerations In mobile networks, the signaling of DTMF tones is implemented differently, depending on the signaling direction. A mobile originated DTMF tone is signaled using START/STOP DTMF messages which are hauled through various protocols upwards into the core network. Contrary to that, a mobile terminated DTMF tone is not transfered as an out of band message. Instead, in-band signaling is used, which means a tone is injected early inside a PBX or MGW. When using {program-name} with its built in MNCC functionality a mobile originated DTMF message will not be translated into an in-band tone. Therefore, sending DTMF will not work when internal MNCC is used. For external MNCC, the network integrator must make sure that the back-end components are configured properly in order to handle the two different signaling schemes depending on the signaling direction. NOTE: osmo-sip-connector will translate MNCC DTMF signaling into sip-info messages. DTMF signaling in the opposite direction is not possible. osmo-sip-connector will reject sip-info messages that attempt to signal a DTMF tone. === MNCC protocol description The protocol follows the primitives specified in 3GPP TS 04.07 Chapter 7.1. The encoding of the primitives is provided in the `mncc.h` header file in {program-name}'s source tree, which uses some common definitions from `osmocom/gsm/mncc.h` (part of libosmocore.git). However, Osmocom's MNCC specifies a number of additional primitives beyond those listed in the 3GPP specification. The different calls in the network are distinguished by their callref (call reference), which is a unique unsigned 32bit integer. ==== MNCC_HOLD_IND Direction: {program-name} -> Handler A 'CC HOLD' message was received from the MS. ==== MNCC_HOLD_CNF Direction: Handler -> {program-name} Acknowledge a previously-received 'CC HOLD' message, causes the transmission of a 'CC HOLD ACK' message to the MS. ==== MNCC_HOLD_REJ Direction: Handler -> {program-name} Reject a previously-received 'CC HOLD' message, causes the transmission of a 'CC HOLD REJ' message to the MS. ==== MNCC_RETRIEVE_IND Direction: {program-name} -> Handler A 'CC RETRIEVE' message was received from the MS. ==== MNCC_RETRIEVE_CNF Direction: Handler -> {program-name} Acknowledge a previously-received 'CC RETRIEVE' message, causes the transmission of a 'CC RETRIEVE ACK' message to the MS. ==== MNCC_RETRIEVE_REJ Direction: Handler -> {program-name} Reject a previously-received 'CC RETRIEVE' message, causes the transmission of a 'CC RETRIEVE REJ' message to the MS. ==== MNCC_USERINFO_REQ Direction: {program-name} -> Handler Causes a 'CC USER INFO' message to be sent to the MS. ==== MNCC_USERINFO_IND Direction: {program-name} -> Handler Indicates that a 'CC USER-USER' message has been received from the MS. ==== MNCC_BRIDGE Direction: Handler -> {program-name} Requests that the TCH (voice) channels of two calls shall be inter-connected. This is the old-fashioned way of using MNCC, historically required for circuit-switched BTSs whose TRAU frames are received via an E1 interface card, and works only when the TCH channel types match. NOTE: Internal MNCC uses MNCC_BRIDGE to connect calls directly between connected BTSs or RNCs, in effect disallowing calls between mismatching TCH types and forcing all BTSs to be configured with exactly one TCH type and codec. This is a limitation that will probably remain for the old OsmoNITB. For the new OsmoMSC, the MNCC_BRIDGE command will instruct the separate OsmoMGW to bridge calls, which will be able to handle transcoding between different TCH as well as 3G (IuUP) payloads (but note: not yet implemented at the time of writing this). Hence an external MNCC may decide to bridge calls directly between BTSs or RNCs that both are internal to the OsmoMSC, for optimization reasons. ==== MNCC_FRAME_RECV Direction: Handler -> {program-name} Enable the forwarding of TCH voice frames via the MNCC interface in {program-name}->Handler direction for the specified call. ==== MNCC_FRAME_DROP Direction: Handler -> {program-name} Disable the forwarding of TCH voice frames via the MNCC interface in {program-name}->Handler direction for the specified call. ==== MNCC_LCHAN_MODIFY Direction: Handler -> {program-name} Modify the current dedicated radio channel from signalling to voice, or if it is a signalling-only channel (SDCCH), assign a TCH to the MS. ==== MNCC_RTP_CREATE Direction: Handler -> {program-name} Create a RTP socket for this call at the BTS/TRAU that serves this BTS. ==== MNCC_RTP_CONNECT Direction: Handler -> {program-name} Connect the RTP socket of this call to the given remote IP address and port. ==== MNCC_RTP_FREE Direction: Handler -> {program-name} Release a RTP connection for one given call. ==== GSM_TCHF_FRAME Direction: both Transfer the payload of a GSM Full-Rate (FR) voice frame between the {program-name} and an external MNCC handler. ==== GSM_TCHF_FRAME_EFR Direction: both Transfer the payload of a GSM Enhanced Full-Rate (EFR) voice frame between the {program-name} and an external MNCC handler. ==== GSM_TCHH_FRAME Direction: both Transfer the payload of a GSM Half-Rate (HR) voice frame between the {program-name} and an external MNCC handler. ==== GSM_TCH_FRAE_AMR Direction: both Transfer the payload of a GSM Adaptive-Multi-Rate (AMR) voice frame between the {program-name} and an external MNCC handler. ==== GSM_BAD_FRAME Direction: {program-name} -> Handler Indicate that no valid voice frame, but a 'bad frame' was received over the radio link from the MS. ==== MNCC_START_DTMF_IND Direction: {program-name} -> Handler Indicate the beginning of a DTMF tone playback. ==== MNCC_START_DTMF_RSP Direction: Handler -> {program-name} Acknowledge that the DTMF tone playback has been started. ==== MNCC_START_DTMF_REJ Direction: both Indicate that starting a DTMF tone playback was not possible. ==== MNCC_STOP_DTMF_IND Direction: {program-name} -> Handler Indicate the ending of a DTMF tone playback. ==== MNCC_STOP_DTMF_RSP Direction: Handler -> {program-name} Acknowledge that the DTMF tone playback has been stopped.