diff options
Diffstat (limited to 'doc/manuals')
31 files changed, 2219 insertions, 116 deletions
diff --git a/doc/manuals/Makefile.am b/doc/manuals/Makefile.am index c86f21563..8b2a8eff9 100644 --- a/doc/manuals/Makefile.am +++ b/doc/manuals/Makefile.am @@ -1,10 +1,13 @@ EXTRA_DIST = aoip-mgw-options.adoc \ aoip-mgw-options-docinfo.xml \ + osmobsc-cbsp.adoc \ + osmobsc-cbsp-docinfo.xml \ osmobsc-usermanual.adoc \ osmobsc-usermanual-docinfo.xml \ osmobsc-vty-reference.xml \ osmux-reference.adoc \ osmux-reference-docinfo.xml \ + cbsp \ chapters \ message-sequences \ mgw \ @@ -13,9 +16,10 @@ EXTRA_DIST = aoip-mgw-options.adoc \ vty if BUILD_MANUALS - ASCIIDOC = osmobsc-usermanual.adoc osmux-reference.adoc aoip-mgw-options.adoc + ASCIIDOC = osmobsc-usermanual.adoc osmobsc-cbsp.adoc osmux-reference.adoc aoip-mgw-options.adoc include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.asciidoc.inc osmobsc-usermanual.pdf: $(srcdir)/chapters/*.adoc $(srcdir)/chapters/*.dot + osmobsc-cbsp.pdf: $(srcdir)/cbsp/*.adoc #$(srcdir)/cbsp/*.dot $(srcdir)/abis/*.msc aoip-mgw-options.pdf: $(srcdir)/aoip-mgw-options.adoc $(srcdir)/mgw/*.msc VTY_REFERENCE = osmobsc-vty-reference.xml diff --git a/doc/manuals/aoip-mgw-options-docinfo.xml b/doc/manuals/aoip-mgw-options-docinfo.xml index 080959443..4cec92fa7 100644 --- a/doc/manuals/aoip-mgw-options-docinfo.xml +++ b/doc/manuals/aoip-mgw-options-docinfo.xml @@ -7,6 +7,14 @@ Initial version of the proposal for internal discussion. </revremark> </revision> + <revision> + <revnumber>1.0</revnumber> + <date>November 2020</date> + <authorinitials>Harald Welte</authorinitials> + <revremark> + Update with changes on what was actually implemented in recent years; change from future to past tense. + </revremark> + </revision> </revhistory> <authorgroup> @@ -24,7 +32,7 @@ </authorgroup> <copyright> - <year>2017</year> + <year>2017-2020</year> <holder>sysmocom - s.f.m.c. GmbH</holder> </copyright> diff --git a/doc/manuals/aoip-mgw-options.adoc b/doc/manuals/aoip-mgw-options.adoc index 124c03fda..62163ccc4 100644 --- a/doc/manuals/aoip-mgw-options.adoc +++ b/doc/manuals/aoip-mgw-options.adoc @@ -5,8 +5,8 @@ This document serves as a paper to illustrate the different configurations of OsmoBSC in terms of integration with BTSs and MSCs. -The document should accompany us in the 2017 development cycle which -includes the _death of the NITB_, i.e. the move away from OsmoNITB to +The document was created ahead of the 2017 development cycle which +included the _death of the NITB_, i.e. the move away from OsmoNITB to having OsmoBSC in all configurations, whether with a proprietary/external MSC or with OsmoMSC. @@ -24,8 +24,13 @@ such as === Classic GSM RAN with E1 based Abis and E1 A -This configuration was actually never supported by OpenBSC, as E1 BTS -support was so far for NITB only, but not for OsmoBSC. +This is how GSM was originally specified when it was introduced: E1/T1 +circuits on all interfaces, no IP anywhere. + +This configuration was actually never supported by OpenBSC, as E1 +support was always only on the Abis side (OpenBSC, OsmoNITB and today OsmoBSC). + +We never supported A interface over E1. It could be done if there was a need. [mscgen] ---- @@ -53,11 +58,11 @@ Release 7 of 3GPP included an official specification on how an interoperable A-over-IP (AoIP) interface shall look like. As more modern MSCs at operators tend to favor implementing 3GPP AoIP -rather than the proprietary SCCPlite based A interface, it becomes +rather than the proprietary SCCPlite based A interface, it became necessary for OsmoBSC to support this. At the same time, for compatibility reasons, the classic SCCPlite -support shall be kept, if possible with reasonable effort. +support is kept in OsmoBSC as a configuration option. [mscgen] ---- @@ -65,11 +70,16 @@ include::{srcdir}/mgw/osmo-bsc-new-mgw.msc[] ---- -=== OsmoBSC 2017+: 3GPP AoIP + Abis/E1 +=== OsmoBSC 2020+: 3GPP AoIP + Abis/E1 + +Since OsmoNITB was deprecated in 2017, and OsmoBSC only supported Abis/IP, +we temporarily lost the ability to use classic E1 based BTSs. In 2020, +we re-introduced and re-tested the support of Abis/E1. -Since OsmoNITB will soon be deprecated, we will use OsmoBSC in all -Osmocom GSM ntework setups, requiring the support for classic E1/T1 -based BTSs from OsmoBSC. +Fro the control plane of Abis (RSL, OML) the E1 support via libosmo-abis +never really ceased to exist. But for the user plane, E1 support had to be +introduced to osmo-mgw, and osmo-bsc needed to be taught how to configure +E1 endpoints at the MGW. The related call flow for such setups looks like this: [mscgen] ---- diff --git a/doc/manuals/cbsp/messages.adoc b/doc/manuals/cbsp/messages.adoc new file mode 100644 index 000000000..d595b958f --- /dev/null +++ b/doc/manuals/cbsp/messages.adoc @@ -0,0 +1,73 @@ +== CBSP Messages + +=== List of Messages + +The following tables list the CBSP messages used by OsmoBSC BSC-CBC interface, +grouped by their level of compliance with 3GPP TS 48.049. + +==== Messages Compliant With TS 48.049 + +Specific additions and limitations apply, see the linked sections. + +.Messages compliant with TS 48.049 +[options="header",cols="10%,20%,45%,5%,20%"] +|=== +| TS 48.049 § | This document § | Message | <-/-> | Received/Sent by OsmoBSC +| 8.1.3.1 | - | WRITE-REPLACE | <- | Received +| 8.1.3.2 | - | WRITE-REPLACE COMPLETE | -> | Sent +| 8.1.3.3 | - | WRITE-REPLACE FAILURE | -> | Sent +| 8.1.3.4 | - | KILL | <- | Received +| 8.1.3.5 | - | KILL COMPLETE | -> | Sent +| 8.1.3.6 | - | KILL FAILURE | -> | Sent +| 8.1.3.10 | - | MESSAGE STATUS QUERY | <- | Received +| 8.1.3.11 | - | MESSAGE STATUS QUERY COMPLETE | -> | Sent +| 8.1.3.12 | - | MESSAGE STATUS QUERY FAILURE | -> | Sent +| 8.1.3.16 | - | RESET | <- | Received +| 8.1.3.17 | - | RESET COMPLETE | -> | Sent +| 8.1.3.18 | <<RESET_FAILURE>> | RESET FAILURE | -> | Sent +| 8.1.3.18a | <<KEEP_ALIVE>> | KEEP-ALIVE | <- | Received +| 8.1.3.18b | - | KEEP-ALIVE COMPLETE | -> | Sent +| 8.1.3.19 | <<RESTART>> | RESTART | -> | Sent +|=== + +==== Messages Not Implemented by OsmoBSC + +.3GPP TS 48.049 messages not implemented by OsmoBSC +[options="header",cols="30%,45%,5%,20%"] +|=== +| TS 48.049 § | Message | <-/-> | Received/Sent by OsmoBSC +| 8.1.3.7 | LOAD QUERY | <- | Received +| 8.1.3.8 | LOAD QUERY COMPLETE | -> | Sent +| 8.1.3.9 | LOAD QUERY FAILURE | -> | Sent +| 8.1.3.13 | SET-DRX | <- | Received +| 8.1.3.14 | SET-DRX COMPLETE | -> | Sent +| 8.1.3.15 | SET-DRX FAILURE | -> | Sent +| 8.1.3.20 | FAILURE | -> | Sent +| 8.1.3.21 | ERROR INDICATION | -> | Sent +|=== + + +=== Message Limitation Details + +[[RESET_FAILURE]] +==== RESET FAILURE + +Encoding of this message is implemented, but there is currently no +condition in the OsmoBSC code that would make a RESET operation fail on +an existing cell, except if the CBC were to identify +a non-existent cell in its _Cell List IE_. + +[[KEEP_ALIVE]] +==== KEEP-ALIVE + +The message is received and generates a corresponding KEEP-ALIVE +COMPLETE answer. However, the _Keep Alive Repetition Period IE_ is not +interpreted. + +[[RESTART]] +==== RESTART + +The RESTART message is sent only at the time of establishment of every +CBSP link. It is not sent when subsequent cells become available during +runtime of the CBSP link. + diff --git a/doc/manuals/cbsp/procedures.adoc b/doc/manuals/cbsp/procedures.adoc new file mode 100644 index 000000000..192014916 --- /dev/null +++ b/doc/manuals/cbsp/procedures.adoc @@ -0,0 +1,83 @@ +== CBSP Procedures + +=== List of Procedures + +The following tables list the CBSP procedures used by the OsmoBSC BSC-CBC interface, +grouped by their level of compliance with 3GPP TS 48.049. + +==== Procedures Compliant With TS 48.049 + +Specific additions and limitations apply, see the linked sections. + +.Procedures compliant with TS 48.049 +[options="header",cols="10%,20%,40%,30%"] +|=== +| TS 48.049 § | This document § | Procedure | Originated/Terminated by OsmoBSC +| 7.2 | <<PROC_WRITE_REPLACE>> | Write-Replace | Terminated +| 7.3 | - | Kill | Terminated +| 7.5 | - | Message Status Query | Terminated +| 7.7a | <<PROC_KEEP_ALIVE>> | Keep Alive | Terminated +| 7.8 | <<RESTART_IND>> | Restart Indication | Originated +|=== + + +[[PROC_WRITE_REPLACE]] +===== Write-Replace + +Procedures for _Write_ and _Replace_ of CBS messages as per 3GPP TS 48.049 Section 7.2.2.2 +are fully supported. + +Procedures for _Write_ and _Replace_ of ETWS messages as per 3GPP TS +48.059 Section 7.2.2.2 are fully supported. Transmission of the ETWS +Primary Notification is implemented as follows, assuming related support +is present in the related BTS and PCU software (true for OsmoBTS >= 1.2.0 +and OsmoPCU >= 0.8.0): + +* broadcast to MS in idle mode / packet idle mode by sending a + vendor-specific A-bis RSL message to each affected BTS. A + vendor-specific mechanism is needed as 3GPP TS 48.058 does not specify + any standard message for this. See the section on _Osmocom ETWS + Command_ in <<osmobts-abis-spec>> for more details. +* broadcast to MS in dedicated mode by sending the ETWS PN via every + currently active dedicated channel (SDCCH, FACCH) within the affected + BTSs. + +As an additional clarification to 3GPP TS 48.049, OsmoBSC rejects (via +WRITE-REPLACE FAILURE) any _write_ procedure for an emergency message if +there already is another emergency message active in a cell. The +_replace_ procedure must be used (by specifying the _Old Serial Number +IE_) if the only existing emergency message of a cell shall be replaced. + +[[PROC_KEEP_ALIVE]] +===== Keep-Alive + +The Keep-Alive procedure is implemented only in as far as incoming +Keep-Alive requests are responded to. + +The BSC currently does not use the _Keep Alive Repetition Period IE_. +This is permitted as 3GPP TS 48.049 states the information _may_ be used +by the BSC. + +[[PROC_RESTART_IND]] +===== Restart Indication + +Restart indications are currently only sent whenever any BSC-CBC link is +established. They are not sent once subsequent cells become available +or are re-initialized due to A-bis link failure. + +However, CBSP state for both CBS and Emergency messages is kept +persistent in the BSC and if cells reboot / restart during the duration +of a CBS / emergency message, they will resume broadcasts as expected. + + +==== Procedures Not Implemented by OsmoBSC + +.3GPP TS 48.049 procedures not implemented by OsmoBSC +[options="header",cols="30%,40%,30%"] +|=== +| TS 48.049 § | Procedure | Originated/Terminated by OsmoBSC +| 7.4 | Load Status Enquiry | Terminated +| 7.6 | Set DRX | Terminated +| 7.9 | Failure Indication | Originated +| 7.10 | Error Indication | Originated +|=== diff --git a/doc/manuals/chapters/aoip-flows.adoc b/doc/manuals/chapters/aoip-flows.adoc new file mode 100644 index 000000000..dd9f809c3 --- /dev/null +++ b/doc/manuals/chapters/aoip-flows.adoc @@ -0,0 +1,107 @@ +== AoIP message flow examples + +The flow diagrams / ladder diagrams of this section are intended to +provide some examples on how AoIP procedures work. We hope they will be +useful in understanding the interface better and aid in debugging any +related issues. + +=== AoIP interface bring-up + +This Figure shows the exchange of messages of a BSC when it is +establishing its AoIP interface from scratch, for example because it has +just been started up. We assume the BSC/CN has already been fully +brought up, so no SCTP/M3U*A bring-up between MSC and STP is dieplayed. + +The diagram shows only one possible scenario. + +Depending on the MSC implementation, in between the BSC and the MSC +there may be either + +* a dedicated STP (or multiple replicated STPs) +* no dedicated STP, as the functionality is implemented inside the MSC +* an entire SS7 network between BSC and MSC, with multiple STP, SGW, + elements switching messages from the BSCs to the MSCs. + +The configuration details that need to be known to the BSC at start-up +time are: + +* at SCTP level +** remote IP addresses to which it should establish a SCTP association +** SCTP port number for M3UA at the STP +* at M3UA level +** routing key (0 for none) +** local BSC-side SS7 point code +** remote MSC-side SS7 point code + +There possibly may be more configuration details, such as + +* multiple local and/or remote IP addresses for SCTP multi-homing +* a fixed local (BSC side) IP address and/or SCTP port (default: + dynamic/random) + +.AoIP interface bring-up between BSC and MSC +[mscgen] +---- +include::../message-sequences/a_interface_bringup.msc[] +---- + +For the purpose of clairty, SCTP-level acknowledgement chunks are not +shown. Those are automatically generated by the receiver for every +DATA chunk received in order to confirm its reception and to allow the +transmitter to re-transmit in case of packet loss. + +==== SCTP multi-homing + +If SCTP multi-homing is used, the additional IP addresses are typically +exchanged via additional information elements in the INIT/INIT_ACK +chunks at connection establishment. They may also change at a later +point. + +==== MSC pooling + +If there is MSC pooling configured, there is typically still only one +M3UA ASP / SCTP association. The different MSCs are addressed on the +SCCP point-code level. It's the STPs job to route the messages based +on point codes to the respective MSC. + +The BSC will try to establish BSSAP to each of the MSCs in the pool, +using a separate BSSAP reset procedure to each of the pool members +point code. + +See the Chapter _MSC Pooling_ in the OsmoBSC user manual for +configuration examples of this situation. + + +=== MO call establishment on AoIP with user plane + +The following figure shows a simplified version of the messages between +MS, OsmoBTS, OsmoBSC, OsmoMGW@BSC, MSC[-Server] and MSC-MGW in during +the establishment and release of a MO voice call. Particular focus +is given on messages related to the establishment of the RTP based +user plane. + +The fact whether or not the RAN or the CN use media gateways, how they +control their respective media gateway, and whether there are multiple +media gateways for load distribution is a private implementation detail +of either RAN or CN. Either side does not need to know the +internal structure of the other side, since the RTP endpoint parameters +are signaled for each call individually over the A interface. + +The signaling between the BSC-colocated MGW and OsmoBSC is IETF MGCP +(Media Gateway Control Protocol). + +The signaling between the MSC[-Server] and the MGW is internal to the +CN. It is typically based on MEGACO/H.248. + +As only the BSC and the MSC exchange 3GPP specified signaling messages, +there is no direct interaction between the RAN and the CN side MGW. +They only exchange RTP and associated RTCP. + +In many real deployments, OsmoMGW will have a different IP address on +the BTS/Abis facing interface than on the MSC/A facing interface. As +a simplification, this has been omitted in the figure. + +[mscgen] +---- +include::../message-sequences/mo_call-bsc-msc-mgw-aoip.msc[] +---- diff --git a/doc/manuals/chapters/bsc.adoc b/doc/manuals/chapters/bsc.adoc index 0d3ded5c4..bdc3d2bb1 100644 --- a/doc/manuals/chapters/bsc.adoc +++ b/doc/manuals/chapters/bsc.adoc @@ -63,18 +63,18 @@ Those timers can be configured using the `timer tXXXX` command. .Configurable Timers |=== |node|timer|default|description -|network|t3101|10|Timeout for 'Immediate Assignment' (sec) -|network|t3103|?|Timeout for Handover (sec) -|network|t3105|40|Repetition of 'Physical Information' (sec) -|network|t3107|?|? -|network|t3109|?|RSL SACCH deactivation timeout (sec) -|network|t3111|?|RSL timeout to wait before releasing the RF channel (sec) -|network|t3113|60|Time to try paging for a subscriber (sec) -|network|t3115|?|? -|network|t3117|?|? -|network|t3119|?|? +|network|t3101|3|Timeout for 'Immediate Assignment' (sec) +|network|t3103|5|Timeout for Handover (sec) +|network|t3105|100|Repetition of 'Physical Information' (millisec) +|network|t3107|5|? +|network|t3109|5|RSL SACCH deactivation timeout (sec) +|network|t3111|2|RSL timeout to wait before releasing the RF channel (sec) +|network|t3113|7|Time to try paging for a subscriber (sec) +|network|t3115|10|? +|network|t3117|10|? +|network|t3119|10|? |network|t3122|10|Waiting time after 'Immediate Assignment Reject' -|network|t3141|?|? +|network|t3141|10|? |=== //TODO: split between BSC and MSC timers @@ -99,13 +99,11 @@ detected during cell selection. Uplink DTX is possible on any TRX, and serves primarily two uses: -possible on any TRX, and serves primarily two uses: - . reducing the MS battery consumption by transmitting at a lower duty cycle . reducing the uplink interference caused in surrounding cells that re-use the same ARFCN. -DTS for both uplink and downlink is implemented in the BTS. Not all BTS +DTX for both uplink and downlink is implemented in the BTS. Not all BTS models support it. The Osmocom BSC component can instruct the BTS to enable or disable diff --git a/doc/manuals/chapters/bts-examples.adoc b/doc/manuals/chapters/bts-examples.adoc index 58cb3ab17..1f3652bbe 100644 --- a/doc/manuals/chapters/bts-examples.adoc +++ b/doc/manuals/chapters/bts-examples.adoc @@ -26,13 +26,13 @@ network type nanobts <2> band DCS1800 <3> cell_identity 0 - location_area_code 1 + location_area_code 0x0001 training_sequence_code 7 base_station_id_code 63 ms max power 15 cell reselection hysteresis 4 rxlev access min 0 - channel allocator ascending + channel allocator mode set-all ascending rach tx integer 9 rach max transmission 7 ipa unit-id 1801 0 <4> @@ -104,13 +104,13 @@ network type nanobts band DCS1800 cell_identity 0 - location_area_code 1 + location_area_code 0x0001 training_sequence_code 7 base_station_id_code 63 ms max power 15 cell reselection hysteresis 4 rxlev access min 0 - channel allocator ascending + channel allocator mode set-all ascending rach tx integer 9 rach max transmission 7 ipa unit-id 1800 0 <1> @@ -174,3 +174,120 @@ network For building a multi-TRX setup, you also need to connect the TIB cables between the two nanoBTS units, as well as the coaxial/RF AUX cabling. ==== + +=== Example configuration for OsmoBSC with E1 BTS + +The following configuration sample illustrates the usage of BTSs that are +connected via an E1/T1 backhaul. + +.OsmoBSC configured for single-TRX E1 Ericsson DUG20 +==== +---- +e1_input <1> + e1_line 0 driver dahdi + e1_line 0 port 3 +network + network country code 1 + mobile network code 1 + encryption a5 0 + neci 1 + handover 0 + bts 0 + type rbs2000 + band GSM900 + om2000 version-limit oml gen 12 rev 10 <2> + cell_identity 0 + location_area_code 0x0001 + training_sequence_code 7 + base_station_id_code 63 + ms max power 15 + cell reselection hysteresis 4 + rxlev access min 0 + channel allocator mode set-all ascending + rach tx integer 9 + rach max transmission 7 + oml e1 line 0 timeslot 1 sub-slot full <3> + oml e1 tei 62 <4> + gprs mode none + is-connection-list add 4 512 12 <5> + is-connection-list add 16 524 12 + is-connection-list add 28 536 12 + is-connection-list add 40 548 12 + trx 0 + rf_locked 0 + arfcn 123 + nominal power 42 + max_power_red 12 + rsl e1 line 0 timeslot 1 sub-slot full <6> + rsl e1 tei 0 <7> + timeslot 0 + phys_chan_config CCCH+SDCCH4 + hopping enabled 0 + e1 line 0 timeslot 1 sub-slot full <8> + timeslot 1 + phys_chan_config TCH/F + hopping enabled 0 + e1 line 0 timeslot 2 sub-slot 1 <9> + timeslot 2 + phys_chan_config TCH/F + hopping enabled 0 + e1 line 0 timeslot 2 sub-slot 2 + timeslot 3 + phys_chan_config TCH/F + hopping enabled 0 + e1 line 0 timeslot 2 sub-slot 3 + timeslot 4 + phys_chan_config TCH/F + hopping enabled 0 + e1 line 0 timeslot 3 sub-slot 0 + timeslot 5 + phys_chan_config TCH/F + hopping enabled 0 + e1 line 0 timeslot 3 sub-slot 1 + timeslot 6 + phys_chan_config TCH/F + hopping enabled 0 + e1 line 0 timeslot 3 sub-slot 2 + timeslot 7 + phys_chan_config TCH/F + hopping enabled 0 + e1 line 0 timeslot 3 sub-slot 3 +---- +==== + +<1> In this example we use a dahdi E1 card. This card has 4 ports. Here we use port numer 3. It should be noted that the dahdi driver also requires additional configuration, which is not covered by this manual. + +<2> In this example we use an E1 Ericsson DUG20, which uses an OML dialect, called "OM2000". + +<3> The first usable timeslot on an E1 line is TS1. In this example we will assume that TS1-TS3 are connected to the BTS stright through. TS1 will handle all signaling traffic. Here we assign this timeslot to OML. + +<4> OML always requires a TEI (Terminal Equipment Identifier) to set up. This number can be found in the manual of the BTS. + +<5> This BTS has an built in “Interface Switch” (IS) that offers flexible way to reconfigure the interconnection between the internal components of the BTS and the external E1 line. This depends on the exact BTS type and configuration. + +<6> Similar to OML we assign TS1 to RSL as well. + +<7> Like with OML, RSL also requires a TEI to be configured. Usually each TRX will have a specific TEI assigned. + +<8> CCCH+SDCCH4 will also be mapped on TS1. The traffic for those control channels will be multiplexed alongside the RSL and OML traffic. + +<9> The bandwidth of one E1 timeslot matches the bandwidth of 4 GSM air interface timeslots. The E1 timeslot is split up into four sub-slots, which are then assigned to one GSM air interface timeslot each. Since the first timeslot on the first TRX is already used for signaling we begin the sub-slot counting with sub-slot 1 for alignment reasons. + +=== E1 Line number and MGCP trunk number +The switching of the voice channels is done via OsmoMGW, which acts as a media +converter between E1 and VoIP (RTP). OsmoBSC will use the E1 line number to +address the trunk via MGCP. + +When configuring OsmoMGW, one needs to make sure that the trunk number that is +set up on OsmoMGW, matches the line number that is set up on OsmoBSC. When those +numbers mismatch the trunk cannot be addressed correctly. + +.OsmoMGW trunk configuration that matches the OsmoBSC configuration above +==== +---- + trunk 0 + rtp keep-alive once + no rtp keep-alive + line 0 +---- +====
\ No newline at end of file diff --git a/doc/manuals/chapters/bts.adoc b/doc/manuals/chapters/bts.adoc index 6e7a308c7..d119acca1 100644 --- a/doc/manuals/chapters/bts.adoc +++ b/doc/manuals/chapters/bts.adoc @@ -105,10 +105,10 @@ like this: ---- network bts 0 - type sysmobts + type osmo-bts band DCS1800 description The new BTS in Baikonur - location_area_code 2342 + location_area_code 0x0926 cell_identity 5 base_station_id_code 63 ip.access unit_id 8888 0 @@ -225,7 +225,7 @@ this cell at all. ==== `gprs cell bvci <2-65535>` Configures the 'BSSGP Virtual Circuit Identifier'. It must be unique -between all BGSGP connections to one SGSN. +between all BSSGP connections to one SGSN. NOTE: It is up to the system administrator to ensure all PCUs are allocated an unique bvci. OsmoBSC will not ensure this policy. @@ -272,10 +272,11 @@ specification for the detailed meaning of those timers. === Dynamic Timeslot Configuration (TCH / PDCH) -A dynamic timeslot is in principle a voice timeslot (TCH) that is used to serve -GPRS data (PDCH) when no voice call is active on it. This enhances GPRS -bandwidth while no voice calls are active, which is dynamically scaled down as -voice calls need to be served. This is a tremendous improvement in service over +A dynamic timeslot is in principle a timeslot that is used to serve GPRS data +(PDCH), but that can be switched to be used either for voice (TCH) or signalling +(SDCCH8) when all other static timeslots are already in use. This enhances GPRS +bandwidth while there is no CS load, and is dynamically scaled down as CS +services need to be served. This is a tremendous improvement in service over statically assigning a fixed number of timeslots for voice and data. The causality is as follows: to establish a voice call, the @@ -295,7 +296,7 @@ all BTS models support dynamic channels. .Dynamic timeslot support by various BTS models [cols="50%,25%,25%"] |=== -| |`TCH/F_TCH/H_PDCH` |`TCH/F_PDCH` +| |`DYNAMIC/OSMOCOM` |`DYNAMIC/IPACCESS` |ip.access nanoBTS |- |supported |Ericsson RBS |supported |- |sysmoBTS using _osmo-bts-sysmo_ |supported |supported @@ -310,11 +311,13 @@ non-standard RSL messages used for these timeslot kinds. NOTE: Same as for dedicated PDCH timeslots, you need to enable GPRS and operate a PCU, SGSN and GGSN to provide the actual data service. -==== Osmocom Style Dynamic Timeslots (TCH/F_TCH/H_PDCH) +==== Osmocom Style Dynamic Timeslots (DYNAMIC/OSMOCOM) -Timeslots of the `TCH/F_TCH/H_PDCH` type dynamically switch between TCH/F, -TCH/H and PDCH, depending on the channel kind requested by the MSC. The RSL -messaging for `TCH/F_TCH/H_PDCH` timeslots is compatible with Ericsson RBS. +`DYNAMIC/OSMOCOM` is an alias for `TCH/F_TCH/H_SDCCH8_PDCH`. + +Timeslots of the `DYNAMIC/OSMOCOM` type dynamically switch between TCH/F, +TCH/H, SDCCH8 and PDCH, depending on the channel kind requested by the MSC. The RSL +messaging for these timeslots is compatible with Ericsson RBS. BTS models supporting this timeslot kind are shown in <<dyn_ts_compat>>. @@ -333,10 +336,12 @@ network In OsmoNITB, disabling TCH/F on Osmocom dynamic timeslots is the default. In OsmoBSC, the default is to allow both. -==== ip.access Style Dynamic Timeslots (TCH/F_PDCH) +==== ip.access Style Dynamic Timeslots (DYNAMIC/IPACCESS) + +`DYNAMIC/IPACCESS` is an alias for `TCH/F_PDCH`. -Timeslots of the `TCH/F_PDCH` type dynamically switch between TCH/F and PDCH. -The RSL messaging for `TCH/F_PDCH` timeslots is compatible with ip.access +Timeslots of the `DYNAMIC/IPACCESS` type dynamically switch between TCH/F and PDCH. +The RSL messaging for `DYNAMIC/IPACCESS` timeslots is compatible with ip.access nanoBTS. BTS models supporting this timeslot kind are shown in <<dyn_ts_compat>>. @@ -349,7 +354,7 @@ timeslots to TCH, and no PDCH timeslots would be left for GPRS service. ==== Dynamic Timeslot Configuration Examples -This is an extract of an `osmo-bsc`` config file. A timeslot configuration with +This is an extract of an `osmo-bsc` config file. A timeslot configuration with five Osmocom style dynamic timeslots and one dedicated PDCH may look like this: ---- @@ -361,20 +366,20 @@ network timeslot 1 phys_chan_config SDCCH8 timeslot 2 - phys_chan_config TCH/F_TCH/H_PDCH + phys_chan_config DYNAMIC/OSMOCOM timeslot 3 - phys_chan_config TCH/F_TCH/H_PDCH + phys_chan_config DYNAMIC/OSMOCOM timeslot 4 - phys_chan_config TCH/F_TCH/H_PDCH + phys_chan_config DYNAMIC/OSMOCOM timeslot 5 - phys_chan_config TCH/F_TCH/H_PDCH + phys_chan_config DYNAMIC/OSMOCOM timeslot 6 - phys_chan_config TCH/F_TCH/H_PDCH + phys_chan_config DYNAMIC/OSMOCOM timeslot 7 phys_chan_config PDCH ---- -With the ip.access nanoBTS, only `TCH/F_PDCH` dynamic timeslots are supported, +With the ip.access nanoBTS, only `DYNAMIC/IPACCESS` dynamic timeslots are supported, and hence a nanoBTS configuration may look like this: ---- @@ -386,15 +391,15 @@ network timeslot 1 phys_chan_config SDCCH8 timeslot 2 - phys_chan_config TCH/F_PDCH + phys_chan_config DYNAMIC/IPACCESS timeslot 3 - phys_chan_config TCH/F_PDCH + phys_chan_config DYNAMIC/IPACCESS timeslot 4 - phys_chan_config TCH/F_PDCH + phys_chan_config DYNAMIC/IPACCESS timeslot 5 - phys_chan_config TCH/F_PDCH + phys_chan_config DYNAMIC/IPACCESS timeslot 6 - phys_chan_config TCH/F_PDCH + phys_chan_config DYNAMIC/IPACCESS timeslot 7 phys_chan_config PDCH ---- @@ -469,23 +474,35 @@ network <2> Rotate the generated permanent list subsets every 20 seconds in a fair fashion Furthermore, cells with large number of subscribers and limited overlapping -coverage may become overwhelmed with traffic after the cell starts brodacasting. +coverage may become overwhelmed with traffic after the cell starts broadcasting. This is especially true in areas with little to no reception from other networks. To manage the load, OsmoBSC has an option to further restrict the rotating ACC subset during startup and slowly increment it over time and taking -current load into account. +current channel load into account. +The channel load will always be checked, even after the start up procedure, at +an interval specified by the `access-control-class-ramping-step-interval` VTY +command. It will either keep, increase or decrease the size of the current +rotating ACC subset based on certain thresholds configured by +the `access-control-class-ramping-chan-load` VTY command. +As a result, if ACC ramping is enabled (`access-control-class-ramping`), the +number of concurrent allowed ACCs will start with *1* and will fluctuate over +time based on channel load in the interval *[1, `access-control-rotate`]*. This +means at any time there will be at least *1* allowed ACC which, together with +ACC rotation, will prevent from subscriber being unable to use the network. .Example: Ramp up access to the BTS after startup ---- network bts 0 access-control-class-ramping <1> - access-control-class-ramping-step-interval 30 <2> - access-control-class-ramping-step-size 1 <3> + access-control-class-ramping-step-size 1 <2> + access-control-class-ramping-step-interval 30 <3> + access-control-class-ramping-chan-load 71 89 <4> ---- <1> Turn on access-control-class ramping -<2> Enable more ACCs every 30 seconds -<3> At each step enable one more ACC +<2> At each step enable one more ACC +<3> Check whether to allow more/less ACCs every 30 seconds +<4> The rotate subset size is increased if channel load is < 71%, and decreased if channel load is > 89%. Here a full example of all the mechanisms combined can be found: @@ -502,14 +519,85 @@ bts 0 access-control-class-rotate-quantum 20 <3> access-control-class-ramping <4> access-control-class-ramping-step-size 1 <5> - access-control-class-ramping-step-interval dynamic <6> + access-control-class-ramping-step-interval 30 <6> + access-control-class-ramping-chan-load 71 89 <7> ---- <1> ACCs 5-9 are administratively barred, ie they will never be used until somebody manually enables them in VTY config <2> Allow access through temporary subsets of len=3 from ACC set 0-4: (0,1,2) -> (1,2,3) -> (2,3,4) -> (3,4,0), etc. <3> Each subset iteration will happen every 20 seconds -<4> During startup since ramping is enabled, it will further restrict the rotate subset size parameter (len=3) -<5> The rotate subset size parameter will be increased one ACC slot at a time: len=0 -> len=1 -> len=2 -> len=3 -<6> The time until the subset size is further increased will be calculated based on current channel load +<4> Ramping is enabled: during startup it will further restrict the rotate subset size parameter (start at len=1, end at len=3) +<5> The rotate subset size parameter will be increased or decreased one ACC slot at a time: len=1 -> len=2 -> len=3 +<6> Check to further increase or decrease the rotate subset size based on current channel load is triggered every 30 seconds +<7> The rotate subset size is increased if channel load is < 71%, and decreased if channel load is > 89%. + +=== Configuring FACCH/SACCH repetition + +osmo-bts supports repetition of FACCH, uplink SACCH and downlink SACCH as +described in _3GPP TS 44.006_ <<3gpp-ts-44.006>>. When the feature is enabled +it is applied dynamically, depending on the rf signal quality and MS +capabilities. FACCH/SACCH repetition (or ACCH repetition) repeats the channel +block transmission two times. This allows the transceiver to combine the symbols +from two separate transmissions, which increases the probability that even a +weak signal can be decoded. + +Enabling ACCH repetition is especially recommended when using the AMR speech +codec. AMR already provides a forward error correction that is superior to +the forward error correction used with FACCH or SACCH. ACCH repetition is a +good way to even out this imbalance. + +The VTY configuration allows to enable repetition for all three channel types +separately. For FACCH the operator has the option to restrict the repetition +to LAPDM command frames only. Alternatively it is also possible to allow all +LAPDM frame types for repetition. The following example shows a typical +configuration where ACCH repetition is fully enabled. + +.Example typical configuration of ACCH repetition parameters at VTY BTS node +---- +OsmoBSC(config-net-bts)# repeat dl-facch all +OsmoBSC(config-net-bts)# repeat ul-sacch +OsmoBSC(config-net-bts)# repeat dl-sacch +OsmoBSC(config-net-bts)# repeat rxqual 4 +---- + +It should be noted that unless the repetition is enabled explicitly, the +repetition is turned off by default. If no threshold (see <<acch_rep_thr>>) is +set, the default value 4 (BER >= 1.6%) will be used. The following example shows +a minimal configuration where the repetition is only activated for FACCH LAPDM +command frames. + +.Example minimal configuration of ACCH repetition parameters at VTY BTS node +---- +OsmoBSC(config-net-bts)# repeat dl-facch command +---- + +Since it is not worthwhile to apply any repetition when the signal conditions +are good enough to ensure a reliable transmission in one round, the operator +has the option to set a threshold based on RXQUAL/BER at which the repetition +is switched on. The threshold mechanism implements a hysteresis to prevent +bouncing between repetition on and repetition off. Only when the signal quality +is increased again by two rxqual levels, the repetition is turned off again. It +is even possible to permanently enable repetition, regardless of the signal +quality. + +[[acch_rep_thr]] +.ACCH repetition thresholds +[options="header",cols="20%,40%,40%"] +|=== +|rxqual |enable threshold |disable threshold +|0 |(repetition always on) |(repetition always on) +|1 |asciimath:[BER >= 0.2%] |asciimath:[BER = 0%] +|2 |asciimath:[BER >= 0.4%] |asciimath:[BER = 0%] +|3 |asciimath:[BER >= 0.8%] |asciimath:[BER <= 0.2%] +|4 |asciimath:[BER >= 1.6%] |asciimath:[BER <= 0.4%] +|5 |asciimath:[BER >= 3.2%] |asciimath:[BER <= 0.8%] +|6 |asciimath:[BER >= 6.4%] |asciimath:[BER <= 1.6%] +|7 |asciimath:[BER >= 12.8%] |asciimath:[BER <= 3.2%] +|=== + +NOTE: osmo-bsc only sets the ACCH repetition parameters via RSL. Whether ACCH +repetition can be used depends on the BTS model and osmo-bts version. To +find out if a BTS supports ACCH repetition (BTS_FEAT_ACCH_REP), the VTY +command `show bts` can be used. ==== RACH Parameter Configuration diff --git a/doc/manuals/chapters/chan_alloc.adoc b/doc/manuals/chapters/chan_alloc.adoc new file mode 100644 index 000000000..ae2ce211e --- /dev/null +++ b/doc/manuals/chapters/chan_alloc.adoc @@ -0,0 +1,156 @@ +== Channel allocation + +Radio resource management is one of the main tasks of the Base Station Controller. +This involves selection, activation, and deactivation of logical channels, which +are maintained by connected Base Stations. The number of usable logical channels +is limited by total number of radio carriers and may vary depending on the physical +channel combinations assigned to their timeslots. Thus a major goal of the this +task is to manage all the available resources in an efficient way, shifting the +balance between service quality and the overall capacity. + +=== Channel allocation parameters + +OsmoBSC's channel allocator can be configured via the VTY interface. All +relevant parameters are limited by the scope of a BTS node they belong to. +There is currently no way to define global configuration for all BTS. + +All parameters with their respective default values are listed below: + +---- +network + bts 0 + channel allocator mode chan-req ascending + channel allocator mode assignment ascending + channel allocator mode handover ascending + channel allocator avoid-interference 0 + channel allocator tch-signalling-policy always +---- + +==== Channel allocation modes + +Currently the following channel allocation modes are supported: + +- ascending (default): allocates channels in ascending order, +starting from timeslot 0 of the first TRX (also called C0, the BCCH carrier); +- descending: allocates channels in descending order, +starting from timeslot 7 of the last TRX; +- dynamic (only for assignment): dynamically choose between ascending +and descending order depending on some additional parameters +(see <<chan_alloc_dyn_mode>>). + +NOTE: Regardless of the chosen mode, logical channels (sub-slots) are always +selected in ascending order. For example, if a timeslot is configured as SDCCH/8 +and all 8 sub-slots are not in use, then the first SDCCH(0) sub-slot will be +selected in both ascending and descending modes. + +The allocation mode to be used can be configured using the following VTY command: + +---- +OsmoBSC(config-net-bts)# channel allocator mode ? <1> + set-all Set a single mode for all variants + chan-req Channel allocation for CHANNEL REQUEST (RACH) + assignment Channel allocation for assignment + handover Channel allocation for handover + +OsmoBSC(config-net-bts)# channel allocator mode set-all ? <2> + ascending Allocate Timeslots and Transceivers in ascending order + descending Allocate Timeslots and Transceivers in descending order + +OsmoBSC(config-net-bts)# channel allocator mode assignment ? <3> + ascending Allocate Timeslots and Transceivers in ascending order + descending Allocate Timeslots and Transceivers in descending order + dynamic Dynamic lchan selection based on configured parameters <3> +---- +<1> It's optionally possible to configure different allocation modes for +different allocation causes, e.g. `ascending` for `chan-req` and `descending` +for both `assignment` and `handover`. +<2> `set-all` is equivalent to the old (deprecated) command syntax: +`channel allocator (ascending|descending)`. +<3> The `dynamic` mode can be selected only for `assignment`. + +[[chan_alloc_dyn_mode]] +===== Dynamic channel allocation mode + +There exists an additional channel allocation mode, which can be employed +during a TCH channel allocation for assignment. This mode selects between +ascending and descending order depending on pre-configured parameters: + +- Uplink RxLev threshold and number of samples for averaging, +- C0 (BCCH carrier) channel load threshold. + +This is useful in setups where Tx power of the RF carriers cannot be adjusted +dynamically at run-time and thus no BS Power Control can be performed. In +such setups the BCCH carrier is transmitting at relatively higher power than +the other RF carriers. The key idea is to allocate channels in a smarter way, +so that UEs with poor signal would get channels on carriers with high Tx power, +while UEs with good signal could use carriers with lower Tx power. + +The configuration parameters for dynamic selection are listed below: + +---- +OsmoBSC(config-net-bts)# channel allocator dynamic-param ? + sort-by-trx-power Whether to sort TRX instances by their respective power levels + ul-rxlev Uplink RxLev + c0-chan-load C0 (BCCH carrier) channel load + +channel allocator dynamic-param sort-by-trx-power ? + 0 Do not sort, use the same order as in the configuration file + 1 Sort TRX instances by their power levels in descending order + +OsmoBSC(config-net-bts)# channel allocator dynamic-param ul-rxlev thresh ? + <0-63> Uplink RxLev threshold +OsmoBSC(config-net-bts)# channel allocator dynamic-param ul-rxlev thresh 50 avg-num ? + <1-10> Minimum number of RxLev samples for averaging +OsmoBSC(config-net-bts)# channel allocator dynamic-param c0-chan-load thresh ? + <0-100> Channel load threshold (in %) +---- + +The default values are: + +---- +network + bts 0 + channel allocator dynamic-param sort-by-trx-power 0 <1> + channel allocator dynamic-param ul-rxlev thresh 50 avg-num 2 <2> + channel allocator dynamic-param c0-chan-load thresh 60 <3> +---- +<1> Assume that RF carriers are listed in descending order sorted by Tx power. +<2> Use descending order if AVG of at least two Uplink RxLev samples >= 50 (-60 dBm). +<3> Use descending order if more than 60% logical channels of C0 are occupied. + +NOTE: The final ascending/descending order decision is based on the two conditions. +The descending order will be used only if *both conditions are met*, otherwise the +allocator will use ascending order. + +==== Interference aware channel allocation + +The channel allocator can be configured to prefer logical channels with least +interference, based on interference measurements periodically sent by the BTSs +(see <<interf_rep>>). This is an optional feature, which is disabled by default. + +---- +OsmoBSC(config-net-bts)# channel allocator avoid-interference ? + 0 Ignore interference levels (default). Always assign lchans + in a deterministic order. + 1 In channel allocation, prefer lchans with less interference. +---- + +NOTE: Interference levels are compared within the scope of the whole BTS. This +means that the selection logic may pick channels on the other TRXes, if they are +better according to the interference reports from the BTS. This feature makes +the allocation order non-deterministic and therefore nullifies the meaning of +channel allocation modes described above. + +==== TCH sigalling policy + +By default, in a situation when all SDCCHs are exhausted, OsmoBSC will be using TCH +channels for signalling (e.g for Location Updating or call establishment). This +behavior can be restricted to certain kinds of signalling or disabled completely. + +---- +OsmoBSC(config-net-bts)# channel allocator tch-signalling-policy ? + never Never allow TCH for signalling purposes + emergency Only allow TCH for signalling purposes when establishing an emergency call + voice Allow TCH for signalling purposes when establishing any voice call + always Always allow TCH for signalling purposes (default) +---- diff --git a/doc/manuals/chapters/control.adoc b/doc/manuals/chapters/control.adoc index 6b1609ae5..8009ec72e 100644 --- a/doc/manuals/chapters/control.adoc +++ b/doc/manuals/chapters/control.adoc @@ -27,10 +27,13 @@ TRX-specific commands are additionally prefixed with TRX number e. g. |inform-msc-v1|WO|Yes|Arbitrary value| See <<infomsc>> for details. |rf_locked|RW|No|"0","1"|See <<rfl>> for details. |number-of-bts|RO|No|"<num>"|Get number of configured BTS. +|apply-config-file|WO|No|"<filename>"|Apply VTY config file snippet from file. +|write-config-file|WO|No|"overwrite", "<filename>"|Write running configuration to file. |bts.N.location-area-code|RW|No|"<lac>"|Set/Get LAC (value between (0, 65535)). |bts.N.cell-identity|RW|No|"<id>"|Set/Get Cell Identity (value between (0, 65535)). |bts.N.apply-configuration|WO|No|Ignored|Restart BTS via OML. -|bts.N.send-new-system-informations|WO|No|Ignored|Regenerate System Information messages for given BTS. +|bts.N.send-new-system-informations|WO|No|Ignored|Regenerate and resend System Information messages for given BTS. +|bts.N.send-power-control-defaults|WO|No|Ignored|Resend default power control parameters for given BTS. |bts.N.channel-load|RO|No|"<name>,<used>,<total>"|See <<chanlo>> for details. |bts.N.oml-connection-state|RO|No|"connected", "disconnected", "degraded"|Indicate the status of OML connection of BTS. |bts.N.oml-uptime|RO|No|<uptime>|Return OML link uptime in seconds. @@ -38,6 +41,37 @@ TRX-specific commands are additionally prefixed with TRX number e. g. |bts.N.rf_state|RO|No|"<oper>,<admin>,<pol>"|See <<rfs>> for details. |bts.N.trx.M.arfcn|RW|No|"<arfcn>"|Set/Get ARFCN (value between (0, 1023)). |bts.N.trx.M.max-power-reduction|RW|No|"<mpr>"|See <<mpr>> for details. +|[bts.N.]handover.active|RW|No|"0","1","default"|Enable/disable handover. +|[bts.N.]handover.algorithm|RW|No|"1","2","default"|Choose algorithm for handover decision (hodec1 or hodec2). +|[bts.N.]handover1.window.rxlev.averaging|RW|No|<1-10>,"default"|How many RxLev measurements to use for averaging. +|[bts.N.]handover1.window.rxqual.averaging|RW|No|<1-10>,"default"|How many RxQual measurements to use for averaging. +|[bts.N.]handover1.window.rxlev.neighbor.averaging|RW|No|<1-10>,"default"|How many Neighbor RxLev measurements to use for averaging. +|[bts.N.]handover1.power.budget.interval|RW|No|<1-99>,"default"|How often to check for a better cell (SACCH frames). +|[bts.N.]handover1.power.budget.hysteresis|RW|No|<0-999>,"default"|How many dB stronger must a neighbor be to become a HO candidate. +|[bts.N.]handover1.maximum.distance|RW|No|<0-9999>,"default"|Maximum Timing-Advance value (i.e. MS distance) before triggering HO. +|[bts.N.]handover2.window.rxlev.averaging|RW|No|<1-10>,"default"|How many RxLev measurements to use for averaging. +|[bts.N.]handover2.window.rxqual.averaging|RW|No|<1-10>,"default"|How many RxQual measurements to use for averaging. +|[bts.N.]handover2.window.rxlev.neighbor.averaging|RW|No|<1-10>,"default"|window rxlev neighbor averaging. +|[bts.N.]handover2.power.budget.interval|RW|No|<1-99>,"default"|How many dB stronger must a neighbor be to become a HO candidate. +|[bts.N.]handover2.power.budget.hysteresis|RW|No|<0-999>,"default"|How many dB stronger must a neighbor be to become a HO candidate. +|[bts.N.]handover2.maximum.distance|RW|No|<0-9999>,"default"|Maximum Timing-Advance value (i.e. MS distance) before triggering HO. +|[bts.N.]handover2.assignment|RW|No|"0","1","default"|Enable or disable in-call channel re-assignment within the same cell. +|[bts.N.]handover2.tdma-measurement|RW|No|"full","subset","default"|Define measurement set of TDMA frames. +|[bts.N.]handover2.min.rxlev|RW|No|<-110--50>,"default"|How weak may RxLev of an MS become before triggering HO. +|[bts.N.]handover2.min.rxqual|RW|No|<0-7>,"default"|How bad may RxQual of an MS become before triggering HO. +|[bts.N.]handover2.afs-bias.rxlev|RW|No|<0-20>,"default"|RxLev improvement bias for AFS over other codecs. +|[bts.N.]handover2.afs-bias.rxqual|RW|No|<0-7>,"default"|RxQual improvement bias for AFS over other codecs. +|[bts.N.]handover2.min-free-slots.tch-f|RW|No|<0-9999>,"default"|Minimum free TCH/F timeslots before cell is considered congested. +|[bts.N.]handover2.min-free-slots.tch-h|RW|No|<0-9999>,"default"|Minimum free TCH/H timeslots before cell is considered congested. +|[bts.N.]handover2.max-handovers|RW|No|<1-9999>,"default"|Maximum number of concurrent handovers allowed per cell. +|[bts.N.]handover2.penalty-time.max-distance|RW|No|<0-99999>,"default"|ime to suspend handover for a subscriber after leaving this cell due to exceeding max distance. +|[bts.N.]handover2.penalty-time.failed-ho|RW|No|<0-99999>,"default"|Time to suspend handover for a subscriber after a failed handover into this cell. +|[bts.N.]handover2.penalty-time.failed-assignment|RW|No|<0-99999>,"default"|Time to suspend handover for a subscriber after a failed re-assignment within this cell. +|[bts.N.]handover2.retries|RW|No|<0-9>,"default"|Number of times to immediately retry a failed handover/assignment, before a penalty time is applied. +|handover2.congestion-check|RW|No|"disabled",<1-999>,"now"|Congestion check interval in seconds, "now" triggers immediate congestion check. +|bts.N.neighbor-list.mode|WO|No|"automatic","manual","manual-si5"|Mode of Neighbor List generation. +|bts.N.neighbor-list.add|WO|No|<0-1023>|Add to manual neighbor list. +|bts.N.neighbor-list.del|WO|No|<0-1023>|Delete from manual neighbor list. |=== [[notif]] @@ -90,4 +124,29 @@ RF Ctrl is enabled in the BSC Configuration. Set/Get the value of maximum power reduction. Even values between 0 and 22 are accepted. -FIXME: add variables defined in src/ctrl/control_if.c? +=== add/del neighbor cell + +The control interface allows for editing the neighbor cell configuration. Neighbor +cells can be added or removed during runtime. It is also possible to clear the +entire neighbor list if necessary. + +.Variables available over control interface +[options="header",width="100%",cols="20%,5%,5%,50%,20%"] +|=== +|Name|Access|Trap|Value|Comment +|bts.N.neighbor-bts.add|WO|No|"<num>"|Add neighbor cell by local BTS number. +|bts.N.neighbor-bts.del|WO|No|"<num>"|Delete neighbor cell by local BTS number. +|bts.N.neighbor-lac.add|WO|No|"<lac>[-<arfcn>-<bsic>]"|Add neighbor cell by LAC. +|bts.N.neighbor-lac.del|WO|No|"<lac>[-<arfcn>-<bsic>]"|Delete neighbor cell by LAC. +|bts.N.neighbor-lac-ci.add|WO|No|"<lac>-<ci>[-<arfcn>-<bsic>]"|Add neighbor cell by LAC and CI. +|bts.N.neighbor-lac-ci.del|WO|No|"<lac>-<ci>[-<arfcn>-<bsic>]"|Delete neighbor cell by LAC and CI. +|bts.N.neighbor-cgi.add|WO|No|"<mcc>-<mnc>-<lac>-<ci>[-<arfcn>-<bsic>]"|Add neighbor cell by cgi. +|bts.N.neighbor-cgi.del|WO|No|"<mcc>-<mnc>-<lac>-<ci>[-<arfcn>-<bsic>]"|Delete neighbor cell by cgi. +|bts.N.neighbor-cgi-ps.add|WO|No|"<mcc>-<mnc>-<lac>-<rac>-<ci>[-<arfcn>-<bsic>]"|Add neighbor cell by cgi (Packet Switched, with RAC) +|bts.N.neighbor-cgi-ps.del|WO|No|"<mcc>-<mnc>-<lac>-<rac>-<ci>[-<arfcn>-<bsic>]"|Delete neighbor cell by cgi (Packet Switched, with RAC). +|bts.N.neighbor-clear|WO|No|Ignored|Delete all neighbor cells. +|=== + +NOTE: The bsic-number (<bsic>) can also be set to "any" if no explcit bsic shall be given + +//FIXME: add variables defined in src/ctrl/control_if.c? diff --git a/doc/manuals/chapters/handover.adoc b/doc/manuals/chapters/handover.adoc index d9805f78c..4affe3b41 100644 --- a/doc/manuals/chapters/handover.adoc +++ b/doc/manuals/chapters/handover.adoc @@ -1,4 +1,5 @@ -== Handover +[[cs_handover]] +== CS Handover Handover is the process of moving a continuously used channel (lchan) from one cell to another. Usually, that is an ongoing call, so that phones are able to @@ -144,6 +145,7 @@ more than one neighbor per given ARFCN+BSIC, these values can be re-used any number of times across a network, and even between cells managed by one and the same BSC. +[[config_neigh]] === Configuring Neighbors The most important step to enable handover in OsmoBSC is to configure each cell @@ -221,15 +223,15 @@ network network bts 0 - # this cell's LAC=23 CI=5 - location_area_code 23 + # this cell's LAC=0x0017 CI=5 + location_area_code 0x0017 cell_identity 5 # reference bts 1 neighbor lac-ci 23 6 bts 1 - # this cell's LAC=23 CI=6 - location_area_code 23 + # this cell's LAC=0x0017 CI=6 + location_area_code 0x0017 cell_identity 6 # reference bts 0 neighbor lac-ci 23 5 @@ -250,8 +252,8 @@ desirable to use the `neighbor bts <0-255>` format, or omit the redundant network bts 0 - # this cell's LAC=23 CI=5 - location_area_code 23 + # this cell's LAC=0x0017 CI=5 + location_area_code 0x0017 cell_identity 5 # this cell's ARFCN=1 BSIC=1 trx 0 @@ -261,8 +263,8 @@ network neighbor lac-ci 23 6 arfcn 2 bsic 2 bts 1 - # LAC=23 CI=6 - location_area_code 23 + # LAC=0x0017 CI=6 + location_area_code 0x0017 cell_identity 6 # this cell's ARFCN=2 BSIC=2 trx 0 @@ -284,8 +286,8 @@ Indication and 3.2.1.9 HANDOVER REQUIRED). # BSC Alpha's osmo-bsc.cfg network bts 0 - # this cell's LAC=23 CI=6 - location_area_code 23 + # this cell's LAC=0x0017 CI=6 + location_area_code 0x0017 cell_identity 6 # this cell's ARFCN=2 BSIC=2 trx 0 @@ -297,8 +299,8 @@ network # BSC Beta's osmo-bsc.cfg network bts 0 - # this cell's LAC=42 CI=3 - location_area_code 42 + # this cell's LAC=0x002A CI=3 + location_area_code 0x002A cell_identity 3 # this cell's ARFCN=1 BSIC=3 trx 0 @@ -509,9 +511,11 @@ periodical congestion check attempts to distribute MS to less loaded neighbor cells. Every time, the one MS that will suffer the least RXLEV loss while still reducing congestion will be instructed to move first. -If a cell and its neighbors are all loaded past their `min-free-slots` -settings, the algorithmic aim is equal load: a load-based handover will never -cause the target cell to be more congested than the source cell. +If a cell and its neighbors are all loaded past their `min-free-slots` settings, +the algorithmic aim is to improve the percentage of load above the +`min-free-slots` setting: a load-based handover always requires the target cell +to have a lower load percentage after handover than the source cell had before +handover. The min-free-slots setting is a tradeoff between immediate voice service availability and optimal reception levels. A sane choice could be: @@ -634,6 +638,7 @@ following properties: * EARFCN (EUTRAN Absolute Radio Channel Number) on which the cell broadcasts * Reselection thresholds towards E-UTRAN cells: + [width="30%"] |==== | 0 | 0 dB @@ -642,10 +647,12 @@ following properties: | 3 | 6 dB | ... | ... | 31 | 62 dB -|===== +|==== + * Priority of E-UTRAN frequency: 0 = lowest priority, ..., 7 = highest priority * QRXLEVMIN parameter: Minimum required RX level in the UTRAN FDD cell (dBm), see 3GPP TS 25.304. + [width="30%"] |==== | 0 | -140 dBm @@ -654,6 +661,7 @@ following properties: | ... | ... | 31 | -78 dBm |==== + * Measurement bandwidth in MHz, see 3GPP TS 44.018 and 3GPP TS 44.060. This field specifies the minimum value of the channel bandwidth of all valid E-UTRAN cells on the specified EARFCN. It is defined by the @@ -664,6 +672,7 @@ following properties: station supporting wideband RSRQ measurements shall measure over the indicated number of resource blocks. The field is coded according to the following table: + [width="30%"] |==== | 0 | N_RB = 6 @@ -687,3 +696,123 @@ network 4G neighbor cells can be removed using the same command, just replacing `add` with `del`. + +[[ps_handover]] +== PS Handover + +Packet Switch Handover is mostly managed by the packet switching nodes such as +PCU, SGSN and GGSN. However, the PCU encounters a similar difficulty to that +explained in <<cs_handover>>: that is, it must find a way to translate +ARFCN+BSIC identifiers provided by the MS into the sort of identifiers +understood by the Core Network (SGSN). These identifiers are in this case +composed of RAC+CI (instead LAC+CI), or more specifically, CGI+RAC (named as +"Packet Switched CGI" or "CGI-PS" from now on for convenience). + +Hence, it feels natural extending the <<config_neigh>> storage in the BSC to +also provide Packet Switched related identifiers in order to provide the PCU the +required information to do the translations, instead of duplicating the whole +neighbor information in two different network nodes. + +This can be done, similarly to already presented CS related commands in +<<config_neigh>>, by using the `neighbor cgi-ps` VTY command, which allows for +specifying the extra identifier (RAC) required by PS related translations: + +.Example: configuring PS neighbors within the local BSS in osmo-bsc.cfg, identified by CGI-PS (CGI+RAC) +---- +network + bts 0 +neighbor cgi-ps <MCC> <MNC> <LAC> <RAC> <CI> arfcn <0-1023> bsic (<0-63>|any) +---- + +This information should already be present by default if one uses the `local BTS +number` to identify the network, as long as that BTS is properly configured to +have GPRS enabled and the RAC code is set by `gprs routing area <0-255>` +command: + +.Example: configuring PS neighbors within the local BSS in osmo-bsc.cfg, identified by local BTS number +---- +network + bts 0 + gprs mode gprs + gprs routing area 45 + neighbor bts 1 + ... + bts 1 + gprs mode egprs + gprs routing area 48 + neighbor bts 0 + ... +---- + +This PS information is solely used by the Neighbor Resolution Service, aimed at +nodes other than BSC itself, and described below. + +=== Neighbor Address Resolution Service + +This service is provided in order to provide the PCU with a way to translate +ARCFCN+BSIC into CGI-PS in order to use RIM services and accomplish PS +Handovers. + +This interface is Osmocom specific, since the standard doesn't provide any +specifications on how to provide this kind of information to the PCU. + +Since the PCU can be either BSC co-located or BTS co-located (hence on a +different host than BSC), messages may need to be sent over the network at some +point. + +In consequence, it was decided implement a new _Container_ type message in +PCUIF which the PCU can use to directly communicate with the BSC. If the PCU is +BSC co-located, then the BSC can directly communicate over the unix socket. If +the PCU is BTS co-located, then PCU sends PCUIF messages over the unix socket to +the BTS, and the BTS forwards the PCUIF messages transparently over the the IPA +multiplex of the OML connection towards the BSC and back. + +Support for this interface is available by default nowadays in OsmoPCU, OsmoBTS +and OsmoBSC, and requires no specific configuration, it will just work out of +the box. + +==== Neighbor Address Resolution Service CTRL interface (deprecated) + +Before the existence of the PCUIF forwarded over IPA multiplex interface (see +above), the Neighbor Address Resolution Service was implemented by means of a +CTRL interface, similar to the one used in most Osmocom processes (see +<<control>>). + +CAUTION: This interface is nowadays considered deprecated and should not be used +anymore. Any related VTY options should be dropped from configuration files, to +let OsmoPCU use the new interface instead. This section is kept here for a while +as a reference for old deployments using old versions of the programs. + +Due to security concerns, the set of CTRL commands available in this +service is configured in a different IP address and port, since the service +needs to be reachable by all PCU under the BSC. This way the user can still +constrain the regular CTRL port (which may contains lots of configuration +related commands) listening in a more constrained address (eg. localhost). + +By default, this interface is disabled, and it is enabled by configuring the +desired IP address to bind to (and optionally a different port other than +well-known `4248`): + +.Example: Enable and configure Neighbor Resolution Service CTRL interface +---- +network + neighbor-resolution bind 127.0.0.1 5000 +---- + +osmo-pcu will then be able to connect to the BSC and query for resolution during +eg. NACC requests from MS. + +The relevant commands are:: + +* neighbor_resolve_cgi_ps_from_lac_ci: +---- +GET neighbor_resolve_cgi_ps_from_lac_ci.<src_lac>.<src_cell_id>.<dst_arfcn>.<dst_bsic> +GET_REPLY <MCC>-<MNC>-<LAC>-<RAC>-<CI> +---- + +Where the `src_lac` and `src_ci` are provided by BTS/BSC over `PCUIF` interface +during startup (`INFO IND`), and `dst_arfcn` and `dst_bsic` are those of the +neighbor the PCU is willing to request the CGI-PS information. Hence, from the +`src` params the BSC is able to look up the BTS and afterwards apply the +translation of `dst` parameters based on the neighbor information available for +that BTS. diff --git a/doc/manuals/chapters/handover_inter_bsc.dot b/doc/manuals/chapters/handover_inter_bsc.dot index 42decef32..3ff8093d0 100644 --- a/doc/manuals/chapters/handover_inter_bsc.dot +++ b/doc/manuals/chapters/handover_inter_bsc.dot @@ -27,7 +27,7 @@ BTS_a1 -> BTS_b0 [label="(5) BSC decides to do\ninter-BSC Handover",style=dashed {BSC_a,BSC_b} -> MSC [arrowhead=none,label=A] -BSC_a -> MSC [label="(6) --> Handover Required\nto LAC=42 CI=6\n(10) <-- Handover Command",style=dashed,constraint=false,arrowhead=none] +BSC_a -> MSC [label="(6) --> Handover Required\nto LAC=42 CI=3\n(10) <-- Handover Command",style=dashed,constraint=false,arrowhead=none] MSC -> BSC_b [label="(7) <-- Handover Request\n(9) --> Handover Request ACK",style=dashed,constraint=false,arrowhead=none] BSC_b -> BTS_b0 [label="(8) activate new lchan",style=dashed,constraint=false] diff --git a/doc/manuals/chapters/interf_meas.adoc b/doc/manuals/chapters/interf_meas.adoc new file mode 100644 index 000000000..47c524f55 --- /dev/null +++ b/doc/manuals/chapters/interf_meas.adoc @@ -0,0 +1,73 @@ +[[interf_rep]] +== Interference reporting + +According to 3GPP 48.058, section 6.1, the BTS shall periodically report the +interference levels on *idle* channels using the "Radio resource indication" +procedure. This is done by sending the `RF RESource INDication` message, +which is specified in sections 8.6.1 and 9.3.21. + +// TODO: BSC -> MSC reporting (3GPP TS 48.008, section 3.1.3) + +=== Interference reporting parameters + +The interference band is calculated by the BTS based on the `Interference level +Boundaries` and the `Averaging period`. These parameters are sent by the BSC +over the A-bis/OML, and can be configured via the VTY interface. + +Below are the default values for them: + +---- +network + bts 0 + interference-meas avg-period 6 <1> + interference-meas level-bounds -115 <2> -109 -103 -97 -91 -85 <3> +---- +<1> Averaging period (`Intave`) in SACCH multiframe periods (480ms). +<2> Interference level boundary `0` (in dBm). +<3> Interference level boundary `X5` (in dBm). + +The `Intave` parameter defines the averaging and reporting period. With the +default value of 6 SACCH multiframe periods the BTS is instructed to report +averaged interference levels approximately every 3 seconds. + +According to 3GPP TS 48.008, there exist five interference bands and six +`Interference level Boundaries` (`0`, `X1`, ... `X5`). The BTS shall map the +averaged interference levels (initially in dBm) into these 5 bands. + +---- +-115 dBm -109 dBm -103 dBm -97 dBm -91 dBm -85 dBm + | <1> | <2> | <3> | <4> | <5> | <6> + +----------+----------+----------+----------+----------+ + | band 1 | band 2 | band 3 | band 4 | band 5 | + +----------+----------+----------+----------+----------+ +---- +<1> Interference level boundary `0` (outer). +<2> Interference level boundary `X1`. +<3> Interference level boundary `X2`. +<4> Interference level boundary `X3`. +<5> Interference level boundary `X4`. +<6> Interference level boundary `X5` (outer). + +Unfortunately, it's not clearly defined by 3GPP how the BTS is supposed to map +dBm values outside of the outer boundaries (`0` and `X5`) to band values. The +ip.access nanoBTS, for example, would map values -120 dBm and -75 dBm to bands +1 and 5, respectively. osmo-bts replicates this behavior. + +=== PDCH and dynamic timeslot handling + +The BTS may optionally report interference levels for PDCH timeslots. This +may be useful for the BSC to determine whether dynamic PDCH timeslots might +be better used for new circuit switched connections, or whether alternative +PDCH resources should be allocated for interference reasons. + +NOTE: Currently osmo-bsc makes no use of PDCH interference reports, neither +they get forwarded to the BSC co-located PCU over the PCUIF. + +For dynamic timeslots (`DYNAMIC/OSMOCOM` and `DYNAMIC/IPACCESS`), the +following expectations apply: + +* when in TCH/F mode: no interference reports, because the only sub-channel is active; +* when in TCH/H mode: interference reports for *inactive* sub-channels only; +* when in SDCCH mode: interference reports for *inactive* sub-channels only; +* when in PDCH mode: optional interference reports; +** measurements can be performed during IDLE TDMA frames. diff --git a/doc/manuals/chapters/osmux_bsc.adoc b/doc/manuals/chapters/osmux_bsc.adoc index 0a11d17bf..268ffdfc8 100644 --- a/doc/manuals/chapters/osmux_bsc.adoc +++ b/doc/manuals/chapters/osmux_bsc.adoc @@ -14,14 +14,14 @@ one) need to be configured explicitly. ==== {program-name} in a 3GPP AoIP network setup Osmux usage in {program-name} in managed through the VTY command `osmux -(on|off|only)`. Once enabled (`on` or `only`), {program-name} will start -appending the vendor specific _Osmux Support_ IE in _BSSMAP RESET_ and _BSSMAP -RESET-ACK_ message towards the MSC in order to announce it supports Osmux. This -way, the MSC can decide whether to use Osmux or not based on this information -when setting up a call (this time using _Osmux CID_ IE). It should be noted that -this option should not be enabled unless MSC managing {program-name} supports -handling this extension IE (like OsmoMSC), a 3rd-party MSC might otherwise -refuse the related _RESET_/_RESET-ACK_ messages. +(on|off|only)` under the `msc` node. Once enabled (`on` or `only`), +{program-name} will start appending the vendor specific _Osmux Support_ IE in +_BSSMAP RESET_ and _BSSMAP RESET-ACK_ message towards the MSC in order to +announce it supports Osmux. This way, the MSC can decide whether to use Osmux or +not based on this information when setting up a call (this time using _Osmux +CID_ IE). It should be noted that this option should not be enabled unless MSC +managing {program-name} supports handling this extension IE (like OsmoMSC), a +3rd-party MSC might otherwise refuse the related _RESET_/_RESET-ACK_ messages. {program-name} will behave differently during call set up based on the VTY command presented above: @@ -41,3 +41,42 @@ command presented above: calls on the CN-side, this is, if _BSSMAP Assign Request_ from MSC doesn't contain an _Osmux CID_ IE, it will reject the assignment and the call set up will fail. + +==== Osmux in the ip.access Abis interface + +{program-name} can also talk Osmux instead of RTP to an OsmoBTS which supports +the feature. Osmux usage agains the BTS in {program-name} in managed through the +VTY command `osmux (on|off|only)` under the `bts` node. + +If a BTS supports Osmux, it may announce the _OSMUX_ BTS feature towards the BSC +over OML. This way, the {program-name} becomes aware that this BTS supports +using Osmux to transfer voice call user data when the AMR codec is selected. + +It is then up to {program-name} to decide whether to use Osmux or not when +establishing a new call. If {program-name} decides to use Osmux for a given +call, it will instruct its co-located MGW to set up an Osmux connection in the +endpoint (using the `X-Osmux extension`) and then it will forward the received +Osmux CID to the BTS in the the _IPACC CRCX/MDCX_ messages by means of an extra _Osmux +CID_ IE appended to it. +The IP address and port provided in the same messages refer to the +address and port where Osmux frames with the provided CID are expected to be +received. Similarly, the BTS appends an _Osmux CID_ IE to the _IPACC +CRCX/MDCX ACK_ message it generates, this time with its own local Osmux CID, +which {program-name} will in turn forward back to the co-located MGW. +Same goes for the BTS' local IP address and port where Osmux frames are expected +to be received. + +{program-name} will behave differently during call set up based on the VTY +command `use (on|off|only)` under each `bts` node presented above: + +* `off`: {program-name} will never attempt use of Osmux against this BTS (default). +* `on`: {program-name} will use Osmux against the BTS if the BTS announced Osmux + support during OML bringup, and if MGW provided a valid Osmux CID during _MGCP + CRCX_. Otherwise BSC will simply automatically fall back to using RTP for each + call. For non-AMR calls, RTP will always be used. +* `only`: Same as per `on`, except that {program-name} will accept only Osmux + calls on the BTS-side. This is, if _MGCP CRCX ACK_ from MGW doesn't + contain an _Osmux CID_ IE or _IPACC CRCX ACK_ from BSC doesn't + contain an _Osmux CID_ IE, it will reject the assignment and the call set up + will fail. This means also that only AMR calls (`Channel Mode GSM3`) are + allowed. diff --git a/doc/manuals/chapters/power_control.adoc b/doc/manuals/chapters/power_control.adoc new file mode 100644 index 000000000..9b48f1551 --- /dev/null +++ b/doc/manuals/chapters/power_control.adoc @@ -0,0 +1,645 @@ +== Power control + +The objective of power control is to regulate the transmit power of the MS (Uplink) +as well as the BTS (Downlink) in order to achieve the optimal reception conditions, +i.e. a desired signal strength and a desired signal quality. + +There are two advantages of power control: + +- reduction of the average power consumption (especially in the MS), and +- reduction of the co-channel interference for adjacent channel users. + +Power control can be performed either by the BSC, or by the BTS autonomously. +OsmoBSC currently lacks the power control logic, so it cannot act as the regulating +entity, however it's capable to instruct a BTS that supports autonomous power +control to perform the power regulation. This is achieved by including vendor- +specific IEs with power control parameters in the channel activation messages +on the A-bis/RSL interface. + +=== Power control parameters + +Unfortunately, 3GPP specifications do not specify the exact list of power control +parameters and their encoding on the A-bis/RSL interface, so it's up to a BTS/BSC +vendor what to send and in which format. Furthermore, there is no public +documentation on which parameters are accepted by particular BTS models. + +3GPP TS 44.008 nonetheless defines a minimal set of parameters for a general power +control algorithm. OsmoBSC allows to configure these parameters via the VTY +interface, this is further described in the next sections. + +So far only the ip.access specific format is implemented, so it should be possible +to enable power control for nanoBTS. OsmoBTS also accepts this format, but may +ignore some of the received parameters due to incomplete implementation. On the +other hand, OsmoBTS may support some extra parameters coming in Osmocom specific +IEs not supported by nanoBTS, such as those configuring C/I measurement thresholds. + +[[apply_pwr_ctrl]] +==== When the parameters come into effect? + +It depends on how the power control parameters are signaled to the BTS. If a given +BTS vendor/model requires _each_ RSL CHANnel ACTIVation message to contain the full +set of parameters, then changing them in the BSC at run-time would affect all newly +established logical channels immediately. The existing connections would continue +to use parameters which were in use during the time of channel activation. + +For both ip.access nanoBTS and OsmoBTS, the configured parameters are being sent +only once when the A-bis/RSL link is established. In all subsequent RSL messages, +the MS/BS Power Parameters IE will be sent empty. Therefore, changing most of +dynamic power control parameters at run-time would affect neither the existing +nor newly established logical channels. + +It's still possible to "push" a modified set of MS/BS power control parameters to a +BTS that accepts the default parameters at startup without triggering the A-bis/RSL +link re-establishment and thus interrupting the service. The following command +triggers resending of both MS/BS power control parameters: + +.Example: Resending default power control parameters via the VTY +---- +# Resending from the 'enable' node: +OsmoBSC# bts 0 <1> resend-power-control-defaults + +# Resending from any configuration node (note prefix 'do'): +OsmoBSC(config-ms-power-ctrl)# do bts 0 <1> resend-power-control-defaults +---- +<1> BTS number for which to resend default power control parameters. + +.Example: Resending default power control parameters via the CTRL +---- +$ osmo_ctrl.py \ + --host 127.0.0.1 <1> -p 4249 \ + --set "bts.0.send-power-control-defaults" 1 <2> +---- +<1> Remote address of the host running osmo-bsc (localhost in this example). +<2> An arbitrary dummy value (ignored). Required because SET command is used. + +NOTE: The above statement mostly applies to parameters for dynamic power control +mode (see below). Switching between power control modes, as well as changing +static/maximum power values, does not necessarily require resending of parameters. + +=== Power control configuration + +Two identical groups of parameters are available for both MS (Uplink) and BS +(Downlink) power control. This chapter is aimed to put some light on them. + +All parameters can be set via the VTY interface, currently within the scope of +a BTS node. This means that all transceivers will "inherit" the same configuration. + +---- +OsmoBSC(config)# network +OsmoBSC(config-net)# bts 0 +OsmoBSC(config-net-bts)# ? +... + bs-power-control BS (Downlink) power control parameters + ms-power-control MS (Uplink) power control parameters +... +---- + +Either of these commands would lead to a separate node: + +---- +OsmoBSC(config-net-bts)# ms-power-control +OsmoBSC(config-ms-power-ctrl)# list with-flags +... + . l. mode (static|dyn-bts) [reset] + . l. bs-power (static|dyn-max) <0-30> + . lv ctrl-interval <0-31> + . lv step-size inc <2-6> red <2-4> + . lv rxlev-thresh lower <0-63> upper <0-63> + . lv rxqual-thresh lower <0-7> upper <0-7> + . lv ci-thresh (fr-efr|hr|amr-fr|amr-hr|sdcch|gprs) lower <0-30> upper <0-30> + . lv rxlev-thresh-comp lower <0-31> <0-31> upper <0-31> <0-31> + . lv rxqual-thresh-comp lower <0-31> <0-31> upper <0-31> <0-31> + . lv ci-thresh-comp (fr-efr|hr|amr-fr|amr-hr|sdcch|gprs) lower <0-31> <0-31> upper <0-31> <0-31> + . lv no (rxlev-avg|rxqual-avg) + . lv (rxlev-avg|rxqual-avg) params hreqave <1-31> hreqt <1-31> + . lv (rxlev-avg|rxqual-avg) algo (unweighted|weighted|mod-median) + . lv (rxlev-avg|rxqual-avg) algo osmo-ewma beta <1-99> + . lv no ci-avg (fr-efr|hr|amr-fr|amr-hr|sdcch|gprs) + . lv ci-avg (fr-efr|hr|amr-fr|amr-hr|sdcch|gprs) params hreqave <1-31> hreqt <1-31> + . lv ci-avg (fr-efr|hr|amr-fr|amr-hr|sdcch|gprs) algo (unweighted|weighted|mod-median) + . lv ci-avg (fr-efr|hr|amr-fr|amr-hr|sdcch|gprs) algo osmo-ewma beta <1-99> +---- + +NOTE: Flag `v` indicates that a given parameter is vendor specific, so different +BTS vendors/models may ignore or even reject it. Flag `l` indicates that changing +a given parameter at run-time would affect only the new connections. + +==== Power control mode + +Three power control modes exist: + +---- +OsmoBSC(config-ms-power-ctrl)# mode ? + static Instruct the MS/BTS to use a static power level <1> + dyn-bts Power control to be performed dynamically by the BTS itself <2> +OsmoBSC(config-net-bts)# no (bs-power-control|ms-power-control) <3> +---- +<1> Send RSL MS/BS Power IE alone indicating a static power level to the BTS. +<2> Send both RSL MS/BS Power IE and vendor-specific MS/BS Power Parameters IE. +<3> Do not send any power control IEs in RSL CHANnel ACTIVation messages. + +By default, `static` mode is used for BS power control, while `dyn-bts` mode is +automatically enabled for MS power control if vendor-specific format of the power +control parameters (see above) is implemented for particular BTS model. Otherwise +`static` mode is used too. Changing the mode at run-time would not affect already +established connections, only the new ones (check flag `l`). + +For BS power control, there is an additional parameter: + +---- +OsmoBSC(config-bs-power-ctrl)# bs-power ? + static Fixed BS Power reduction value (for static mode) + dyn-max Maximum BS Power reduction value (for dynamic mode) +---- + +that allows to configure the maximum BS power reduction value in `dyn-bts` mode, +and a fixed power reduction value in `static` mode. In the later case, no +attenuation (0 dB) is applied by default (full power). + +==== Power control interval + +Having requested a transmit power level, the MS/BS power control loop may optionally +be suspended for a certain number of SACCH multiframes defined by VTY parameter +`ctrl-interval`. Given that SACCH is relatively slow and transmission of a data block +takes 480 ms, suspension allows an observation of the effect of one power control +decision before initiating the next one. This is mostly important due to the +fact that MS must change the transmit power at nominal steps of 2dB every 60ms +(TS 45.008 sec 4.7.1). As a result, if the network requests the MS to change its +transmit power by several MS Power Levels at a time, the MS will do so gradually +over the next measurement period. Hence, upon next received L1 SACCH block, the +_MS_PWR_ value announced by the MS will match only the one used to transmit the +last block, and so the related measured RxLevel/RxQual values will be +inaccurate. By skipping one or several SACCH blocks, the algorithm will always +use values which match correctly the announced _MS_PWR_ and the measured +RxLevel/RxQual (because the _MS_PWR_ will already have changed and hence will be +kept stable over that measurement period). + +---- +OsmoBSC(config-bs-power-ctrl)# ctrl-interval ? + <0-31> P_CON_INTERVAL, in units of 2 SACCH periods (0.96 seconds) +---- + +3GPP TS 45.008 briefly mentions this parameter in table A.1 (`P_Con_INTERVAL`). + +A small time graph is depicted below for better understanding of the meaning of +values for this parameter, since it is not obvious at all. + +.Example: Suspension interval accomplished by several values of P_CON_INTERVAL +---- +|<-->| - one SACCH multi-frame period +| | +|----|----|----|----|----|----|----|----|----> SACCH multi-frames +a) * * * * * * * * * P_CON_INTERVAL=0 (0.48 s) +b) * * * * * P_CON_INTERVAL=1 (0.96 s) +c) * * * P_CON_INTERVAL=2 (1.92 s, default) +d) * * P_CON_INTERVAL=3 (2.88 s) +e) * * P_CON_INTERVAL=4 (3.84 s) +---- + +The value to use for this parameter is closely related to that of VTY option +`step-size inc <2-6> red <2-4>`, which configures the maximum step (in dB) at +which the MS Power can be requested to changed when the MS Power Control Loop is +triggered. The higher the `step-size`, the more time it will need the MS to do +the necessary ramping of 2 dB steps, and hence the amount of time required for +the MS to settle on the requested MS Power Level for an entire SACCH block. Or +equally, the time the network can start using the full measurement period to +trigger the MS Power Control Loop again with reliable measurements +(`P_CON_INTERVAL`). + +By default, increment `step-size` is set to 4 dB and the decrement `step-size` +is set to 2 dB, hence the MS requiring `4 * 60 = 240` milliseconds. That's less +than 1 measurement period (480 ms), hence only the first measurement period +needs to be skipped. Therefore, a suspension interval of 1 for both +MS/BS power control loops can be used, and so the power control decision is +taken every 960 ms (every second SACCH block period). + +However, OsmoBSC currently uses a default value of `ctrl-interval 2` +(`P_CON_INTERVAL=2`, 1.92s, 3/4 received SACCH blocks are skipped), because +that's the minimum amount of frames required for one loop step to run +completely, that is: BTS fetching measurements and transmitting the new MS Power +Level, then the MS retrieving the MS Power Level, transmitting with that exact +MS Power level during the entire period and then finally submitting the +Measurement Result containing that same MS Power Level. Using a value of +`P_CON_INTERVAL=1` also provides good results, but in that case the loop tends +to produce more temporary power oscillations due to the loop acting on periods +where an older (earlier requested) MS Power level is still in use (and +announced) by the MS. + +.Example: Timeline showing propagation of a new MS Power Level (P_CON_INTERVAL=2) +---- +|<------------->| - one SACCH multi-frame period +| 1 | 2 | 3 | 4 | ---> SACCH multi-frames +|SA0|SA1|SA2|SA3|SA0|SA1|SA2|SA3|SA0|SA1|SA2|SA3|SA0|SA1|SA2|SA3| ---> SACCH bursts +|<1>|...|...|<2>|<3>|...|...|<4>|<5>|...|...|<6>|<7>|...|...|<8>| +---- +<1> BTS sends new requested MS Power Level in header of SACCH +<2> MS receives SACCH block (new MS Power Level) +<3> MS starts ramping towards new MS Power Level (hence potentially variable power used over the period) +<4> MS should already be in desired MS Power Level (for step increments of less-or-equal than 8 dB) +<5> MS starts transmitting at desired MS Power level constantly (ramping is over) +<6> MS builds Measurement Results to be sent on next SACCH period +<7> MS sends the Measurement Results of the previous multiframe to the BTS +<8> BTS receives the Measurement Results from MS on SACCH, starts next loop iteration + + +Setting `ctrl-interval` to 0 increases the interval to 480 ms, so basically no +SACCH block is skipped and MS Power Control loop is triggered upon receival of +every UL SACCH block. + +==== Power change step size + +In order to slow down the reactivity of the power control loop and thus make it more +robust against sporadic fluctuations of the input values (RxLev and either +RxQual or C/I), the transmit power on both Uplink and Downlink is changed +gradually, step by step. + +OsmoBSC allows to configure the step sizes for both increasing and reducing directions +separately. The corresponding power control loop would apply different delta values +to the current transmit power level in order to raise or lower it. + +.Example: Power change step size +---- +network + bts 0 + bs-power-control + mode dyn-bts <1> + bs-power dyn-max 12 <2> + step-size inc 6 red 4 <3> + ms-power-control + mode dyn-bts <1> + step-size inc 4 red 2 <4> +---- +<1> Both MS and BS power control is to be performed by the BTS autonomously. +<2> The BTS is allowed to reduce the power on Downlink up to 12 dB. +<3> On Downlink, BS power can be increased by 6 dB or reduced by 4 dB at once. +<4> On Uplink, MS power can be increased by 4 dB or reduced by 2 dB at once. + +NOTE: In the context of BS power control, terms 'increase' and 'decrease' have the +same meaning as in the context of MS power control: to make the output power stronger +or weaker respectively. Even despite the BS power loop in fact controls the attenuation. + +TIP: It's recommended to pick the values in a way that the increase step is greater than +the reduce step. This way the system would be able to react on signal degradation +quickly, while a good signal would not trigger radical power reduction. + +Both parameters are mentioned in 3GPP TS 45.008, table A.1: + +- Pow_Incr_Step_Size (range 2, 4 or 6 dB), +- Pow_Red_Step_Size (range 2 or 4 dB). + +==== RxLev and RxQual thresholds + +The general idea of power control is to maintain the signal level (RxLev) and quality +(RxQual) within the target ranges. Each of these ranges can be defined as a pair of +the lowest and the highest acceptable values called thresholds. + +The process of RxLev / RxQual threshold comparison is described in 3GPP TS 45.008, +section A.3.2.1. All parameters involved in the process can be found in table +A.1 with the recommended default values. + +.Example: RxLev and RxQual threshold configuration +---- +network + bts 0 + bs-power-control + mode dyn-bts <1> + rxlev-thresh lower 32 upper 38 <2> + rxqual-thresh lower 3 upper 0 <3> +---- +<1> BS power control is to be performed by the BTS autonomously. +<2> RxLev is to be maintained in range 32 .. 38 (-78 .. -72 dBm). +<3> RxQual is to be maintained in range 3 .. 0 (less is better). + +NOTE: For both RxLev and RxQual thresholds, the lower and upper values are included +in the tolerance window. In the example above, RxQual=3 would not trigger the +control loop to increase BS power, as well as RxLev=38 (-72 dBm) would not trigger +power reduction. + +TIP: It's recommended to harmonize the increase step size with the RxLev threshold +window in a way that the former is less or equal than/to the later. For example, +if the RxLev threshold is 32 .. 36 (-78 .. -74 dBm), then the window size is 4 dB, +and thus the increase step should be less or equal (e.g. 2 or 4 dB). + +In 3GPP TS 45.008, lower and upper RxLev thresholds are referred as `L_RXLEV_XX_P` +and `U_RXLEV_XX_P`, while the RxQual thresholds are referred as `L_RXQUAL_XX_P` and +`U_RXQUAL_XX_P`, where the `XX` is either `DL` (Downlink) or `UL` (Uplink). + +The process of threshold comparison actually involves more than just upper and lower +values for RxLev and RxQual. The received "raw" measurements are being averaged and +stored in a circular buffer, so the power change is triggered only if Pn averages out +of Nn averages exceed the corresponding thresholds. + +.Example: RxLev and RxQual threshold comparators +---- +network + bts 0 + bs-power-control + mode dyn-bts <1> + rxlev-thresh lower 32 upper 38 <2> + rxlev-thresh-comp lower 10 12 <3> upper 19 20 <4> + rxqual-thresh lower 3 upper 0 <5> + rxqual-thresh-comp lower 5 7 <6> upper 15 18 <7> +---- +<1> BS power control is to be performed by the BTS autonomously. +<2> L_RXLEV_XX_P=32, U_RXLEV_XX_P=38. +<3> P1=10 out of N1=12 averages < L_RXLEV_XX_P => increase power. +<4> P2=19 out of N2=20 averages > U_RXLEV_XX_P => decrease power. +<5> L_RXQUAL_XX_P=3, U_RXQAUL_XX_P=0. +<6> P3=5 out of N3=7 averages > L_RXQUAL_XX_P => increase power. +<7> P4=15 out of N4=18 averages < U_RXQUAL_XX_P => decrease power. + +==== Carrier-to-Interference (C/I) thresholds + +Carrier-to-Interference (C/I) provides a similar description of link quality to +that provided by RxQual. However, C/I provides higher granularity than RxQual +levels (0-7), hence providing the operator with a more refined way to set up +targets levels and thresholds. C/I measurements can only be used for MS Power +Control, since values are only available on the Uplink when computed by the BTS, +and the MS doesn't provide figure for the Downlink to the BTS/BSC during +measurement Reports. + +Usual C/I value range for MS uplink channels are between 0dB to 30dB, with 9dB +being a usual average target around cell edges. Furthermore, publicly available +studies conclude that different channel types with different codecs used have +different target C/I where signal is considered good enough. This means MS using +a given channel type with better codec capabilities can be instructed to +transmit at lower levels, hence reducing noise or channel interference among MS. + +OsmoBTS MS Power Control Loop algorithm supports using C/I computed +measurements. Related parameters can be configured similar to those of RxLev or +RxQual (see previous section), with the main difference being that instead of +having a global set of parameters, there's one set per channel type, hence +allowing different parametrization based on the channel type in use by the MS. + +.Example: C/I threshold comparators for AMR-FR +---- +network + bts 0 + ms-power-control + mode dyn-bts <1> + ci-thresh amr-fr enable <2> + ci-thresh amr-fr lower 7 upper 11 <3> + ci-thresh-comp amr-fr lower 2 10 <4> upper 3 4 <5> +---- +<1> MS power control is to be performed by the BTS autonomously. +<2> MS power control loop should take C/I into account. +<3> L_CI_AMR_FR_XX_P=7, U_CI_AMR_FR_XX_P=11. +<4> P0=2 out of N1=10 averages < L_CI_AMR_FR_XX_P => increase power. +<5> P1=3 out of N2=4 averages > U_CI_AMR_FR_XX_P => decrease power. + +NOTE: The BSC can instruct a BTS to disable C/I related logic in its +autonomous MS Power Control Loop for a given channel type (hence not taking C/I +measurements into account) by means of setting both related LOWER_CMP_N and +UPPER_CMP_N parameters to zero (see _ci-thresh-comp_ VTY command). For the sake +of easing configuration, a placeholder VTY command to disable C/I for all +channel types is available under VTY node _ms-power-control_ as *_ci-thresh +all disable_*. Afterwards, the new configuration must be deployed to the target +BTS (see <<apply_pwr_ctrl>>). + +==== Measurement averaging process + +3GPP 45.008, section A.3.1 requires that the measurement values reported by both +an MS and the BTS are being pre-processed before appearing on the input of the +corresponding power control loops in any of the following ways: + +- Unweighted average; +- Weighted average, with the weightings determined by O\&M; +- Modified median calculation, with exceptionally high and low values + (outliers) removed before the median calculation. + +The pre-processing is expected to be performed by both MS and BS power control +loops independently, for every input parameter (i.e. RxLev, RxQual and C/I). + +---- +OsmoBSC(config-bs-power-ctrl)# rxlev-avg algo ? + unweighted Un-weighted average + weighted Weighted average + mod-median Modified median calculation + osmo-ewma Exponentially Weighted Moving Average (EWMA) +OsmoBSC(config-bs-power-ctrl)# rxqual-avg algo ? + unweighted Un-weighted average + weighted Weighted average + mod-median Modified median calculation + osmo-ewma Exponentially Weighted Moving Average (EWMA) +---- + +OsmoBTS features a non-standard Osmocom specific EWMA (Exponentially Weighted Moving +Average) based pre-processing. Other BTS models may support additional non-standard +methods too, the corresponding VTY options can be added on request. + +Among with the averaging methods, 3GPP 45.008 also defines two pre-processing +parameters in section A.3.1: + +- Hreqave - defines the period over which an average is produced, in terms of the + number of SACCH blocks containing measurement results, i.e. the number of + measurements contributing to each averaged measurement; + +- Hreqt - is the number of averaged results that are maintained. + +By default, OsmoBSC would not send any pre-processing parameters, so the BTS may +apply its default pre-processing algorithm with default parameters, or may not +apply any pre-processing at all - this is up to the vendor. The pre-processing +parameters need to be configured explicitly as shown in the example below. + +.Example: Explicit pre-processing configuration +---- +network + bts 0 + bs-power-control + mode dyn-bts <1> + rxlev-avg algo unweighted <2> + rxlev-avg params hreqave 4 hreqt 6 <3> + rxqual-avg algo osmo-ewma beta 50 <4> + rxqual-avg params hreqave 2 hreqt 3 <5> + ms-power-control + mode dyn-bts <1> + rxlev-avg algo unweighted <2> + rxlev-avg params hreqave 4 hreqt 6 <3> + rxqual-avg algo osmo-ewma beta 50 <4> + rxqual-avg params hreqave 2 hreqt 3 <5> + ci-avg amr-fr algo osmo-ewma beta 50 <6> + ci-avg amr-fr params hreqave 2 hreqt 3 <7> +---- +<1> Both MS and BS power control is to be performed by the BTS autonomously. +<2> Unweighted average is applied to RxLev values. +<3> RxLev: Hreqave and Hreqt values: 4 out of 6 SACCH blocks produce an averaged measurement. +<4> Osmocom specific EWMA is applied to RxQual values with smoothing factor = 50% (beta=0.5). +<5> RxQual: Hreqave and Hreqt values: 2 out of 3 SACCH blocks produce an averaged measurement. +<6> Osmocom specific EWMA is applied to C/I values on AMR-FR channels with smoothing factor = 50% (beta=0.5). +<7> C/I AMR-FR: Hreqave and Hreqt values: 2 out of 3 SACCH blocks produce an averaged measurement. + +// TODO: Document other power control parameters: +// OsmoBSC(config-net-bts)# ms max power <0-40> +// OsmoBSC(config-net-bts-trx)# max_power_red <0-100> + +=== BCCH carrier power reduction operation + +According to 3GPP TS 45.008, section 7.1, the BCCH carrier (sometimes called C0) of +a BTS shall maintain continuous Downlink transmission at full power in order to +stay "visible" to the mobile stations. Because of that, early versions of this 3GPP +document prohibited BS power reduction on C0. However, a new feature was introduced +in version 13.0.0 (2015-11) - "BCCH carrier power reduction operation". + +This is a special mode of operation, in which the variation of RF power level for +some timeslots is relaxed for the purpose of energy saving. In other words, the +output power on some timeslots, except the timeslot(s) carrying BCCH/CCCH, can be +lower than the full power. In this case the maximum allowed difference is 6 dB. + +Of course, energy saving comes at a price and has impacts to the network KPI. In +particular, it does negatively affect cell reselection performance and does increase +handover failure and call drop rates. This is why BCCH carrier power reduction +operation mode is not enabled by default. More information on potential impact +and the simulation results can be found in 3GPP TR 45.926. + +==== Supported BTS models + +At the time of writing this manual, the only BTS model that can be instructed to +enter or leave the BCCH power reduction mode is osmo-bts-trx. Support for other +BTS vendors/models may be added in the future. + +TIP: If you're using OsmoBTS, make sure that it reports feature #021 "BCCH carrier +power reduction mode" in the feature vector. This can be checked by issuing +`show bts` command in OsmoBSC's VTY interface. + +==== Interworking with static and dynamic power control + +The key difference between BCCH carrier power reduction and the BS power control +is that the former affects *inactive* timeslots (or sub-channels), so only dummy +bursts are affected. The later depends on the Downlink measurement reports sent +by the MS, and thus applies to *active* channels only. However, both features +are interconnected: the maximum BCCH carrier power reduction value constrains +the BS Power value that can be used for dynamic or static BS power control. + +BS power control on the BCCH carrier will not be enabled unless the BTS is in BCCH +carrier power reduction mode of operation. Once it is, the BS power reduction +value in either of `dyn-bts` or `static` modes would be constrained by currently +applied BCCH power reduction value, and thus would never exceed the maximum of 6 dB. + +For example, consider a BTS with BS power control configured to use _dynamic_ mode +and the maximum power reduction of 16 dB. Once this BTS is switched into the BCCH +carrier power reduction mode with the maximum attenuation of 4 dB, the maximum +power reduction value for the BS power loop on the C0 carrier would be 4 dB. + +Moreover, according to 3GPP TS 45.008, between a timeslot used for BCCH/CCCH and +the timeslot preceding it, the difference in output power actually transmitted by +the BTS shall not exceed 3 dB. This means that on some timeslots the power +reduction value can be constrained even further. + +==== Managing BCCH carrier power reduction + +The BCCH carrier power reduction can be controlled via the CTRL and VTY interfaces. +There is currently no logic in OsmoBSC for automatic activation and deactivation +of this mode, so it's up to the network operator (or an external monitoring suite) +when and depending on which factors to toggle it. Setting a value greater than +zero enables the BCCH power reduction mode; setting zero disables it completely. + +.Example: Activating BCCH carrier power reduction via the VTY +---- +OsmoBSC> enable +OsmoBSC# bts 0 <1> c0-power-reduction ? + <0-6> Power reduction value (in dB, even numbers only) +OsmoBSC# bts 0 <1> c0-power-reduction 4 <2> +---- +<1> BTS number for which to activate BCCH carrier power reduction +<2> Maximum BCCH carrier power reduction (in 2 dB steps, 4 dB in this example) + +.Example: Activating BCCH carrier power reduction via the CTRL +---- +$ osmo_ctrl.py \ + --host 127.0.0.1 <1> -p 4249 \ + --set "bts.0.c0-power-reduction" 4 <2> +---- +<1> Remote address of the host running osmo-bsc (localhost in this example) +<2> Maximum BCCH carrier power reduction (in 2 dB steps, 4 dB in this example) + +Once activated, it's possible to introspect the current maximum reduction value: + +.Example: Checking BCCH carrier power reduction state via the VTY +---- +OsmoBSC> enable +OsmoBSC# show bts 0 <1> +BTS 0 is of osmo-bts type in band DCS1800, has CI 0 LAC 1, BSIC 63 (NCC=7, BCC=7) and 2 TRX + Description: (null) + ARFCNs: 751 753 + BCCH carrier power reduction (maximum): 4 dB <2> + ... +---- +<1> BTS number for which to show BCCH carrier power reduction state +<2> Maximum BCCH carrier power reduction currently applied + +.Example: Checking BCCH carrier power reduction state via the CTRL +---- +$ osmo_ctrl.py \ + --host 127.0.0.1 <1> -p 4249 \ + --get "bts.0.c0-power-reduction" +Got message: b'GET_REPLY 3652121201381481804 bts.0.c0-power-reduction 4 <2>' +---- +<1> Remote address of the host running osmo-bsc (localhost in this example) +<2> Maximum BCCH carrier power reduction currently applied + +=== Temporary ACCH overpower + +Temporary overpower (TOP) is a power control technique that allows to improve +SACCH/FACCH performance in case of bad C/I. The key idea of TOP is to +increment the BS transmit power by 2..4 dB only for FACCH/SACCH bursts, while +keeping all voice bursts at the lower (normal) level as determined by the +downlink power control loop. This allows to reduce call drop rate and +increase capacity in deployments with tight frequency reuse. + +NOTE: It's not possible to increase the current BS power beyond the maximum +transmit power level supported by the PHY. Thus if the BTS is already +transmitting at full power, the overpower logic cannot increase it even +further. This is also why TOP must be employed *together with BS power +control*, either static or dynamic. + +The main area of use for TOP is traffic channels employing the AMR (Adaptive +Multi Rate) codec, which is more robust to interference than the associated +signalling channels. While AMR provides sufficient speech quality even at +very low C/I levels, the associated signalling channels may be suffering from +channel coding errors. This imbalance can be compensated by employing TOP, +which can be efficiently combined with the ACCH repetition technique. + +This feature requires no support on the mobile station side and can be used +with UEs implementing the most recent 3GPP relese features, as well as legacy +UEs. However, it needs to be implemented in the BTS. Given that TOP itself +is not specified in 3GPP specifications, osmo-bsc uses Osmocom specific +A-bis/RSL IEs in order to activate it. Therefore, only the recent osmo-bts +versions may be instructed to activate this feature. Make sure that feature +#023 "FACCH/SACCH Temporary overpower" is present in the feature vector. +This can be checked by issuing `show bts` command in OsmoBSC's VTY interface. + +TOP is disabled by default. Below is a configuration example enabling it: + +---- +network + bts 0 + overpower dl-acch 2 <1> + overpower rxqual 4 <2> + overpower chan-mode speech-amr <3> +---- +<1> Overpower of maximum 2 dB for both SACCH and FACCH. +<2> Enable TOP only if RxQual is worse than 4 (BER >= 1.6%). +<3> Permit TOP only for speech channels using AMR codec. + +For advanced use cases, OsmoBSC can be configured to: + +* enable TOP only for FACCH or SACCH selectively, and/or +* keep TOP enabled permanently regardless of the reported RxQual, and/or +* permit TOP for any kind of dedicated channels. + +---- +OsmoBSC(config-net-bts)# overpower ? + dl-acch Enable overpower for both SACCH and FACCH + dl-sacch Enable overpower for SACCH only + dl-facch Enable overpower for FACCH only + +OsmoBSC(config-net-bts)# overpower rxqual 0? + 0 BER >= 0% (always on) + +OsmoBSC(config-net-bts)# overpower chan-mode ? + speech-amr Speech channels using AMR codec (default) + any Any kind of channel mode +---- + +These parameters are indicated to the BTS during a logical channel activation +or modifications procedures, so they can be changed at run-time. diff --git a/doc/manuals/chapters/qos-example.adoc b/doc/manuals/chapters/qos-example.adoc new file mode 100644 index 000000000..2f88b935c --- /dev/null +++ b/doc/manuals/chapters/qos-example.adoc @@ -0,0 +1,46 @@ +==== Full example of QoS for osmo-bsc downlink QoS + +In the below example we will show the full set of configuration required +for both DSCP and PCP differentiation of downlink Abis traffic by osmo-bsc. + +What we want to achieve in this example is the following configuration: + +.DSCP and PCP assignments for osmo-bsc downlink traffic in this example +[options="header",width="30%",cols="2,1,1"] +|=== +|Traffic |DSCP|PCP +|A-bis RSL | 56| 7 +|A-bis RTP | 46| 6 +|A-bis OML | 34| 5 +|=== + +. configure the osmocom program to set the DSCP value +. configure an egrees QoS map to map from priority to PCP + +.Example Step 1: add related VTY configuration to `osmo-bsc.cfg` +---- +... +e1_input + ipa ip-dscp oml 34 + ipa socket-priority oml 5 + ipa ip-dscp rsl 56 + ipa socket-priority rsl 7 +... +---- + +.Example Step 2: egress QoS map to map from socket priority to PCP values +---- +$ sudo ip link set dev eth0.9<1> type vlan egress-qos-map 0:0 5:5 6:6 7:7 <2> +---- +<1> make sure to specify your specific VLAN interface name here instead of `eth0.9`. +<2> create a egress QoS map that maps the priority value 1:1 to the PCP. We also include the + mapping 6:6 from the osmo-mgw example (see <<userman-osmomgw>>) here. + +NOTE:: The settings of the `ip` command are volatile and only active until +the next reboot (or the network device or VLAN is removed). Please refer to +the documentation of your specific Linux distribution in order to find out how +to make such settings persistent by means of an `ifup` hook whenever the interface +comes up. For CentOS/RHEL 8 this can e.g. be achieved by means of an `/sbin/ifup-local +script` (when using `network-scripts` and not NetworkManager). For Debian or Ubuntu, +this typically involves adding `up` lines to `/etc/network/interfaces` or a `/etc/network/if-up.d` +script. diff --git a/doc/manuals/chapters/running.adoc b/doc/manuals/chapters/running.adoc index ae45afcee..70f9d283f 100644 --- a/doc/manuals/chapters/running.adoc +++ b/doc/manuals/chapters/running.adoc @@ -35,8 +35,6 @@ arguments: Set the global log level for logging to stderr. This has mostly been deprecated by VTY based logging configuration, see <<logging>> for more information. -*-l, --local='IP'*:: - Specify the local IP address of the OsmoBSC-MGCP *-r, --rf-ctl 'RFCTL'*:: Offer a Unix domain socket for RF control at the path/filename 'RFCTL' in the file system. @@ -136,7 +134,87 @@ default port for MGCP (2427) on local host (127.0.0.1). Here is an example configuration for a remote MGW: ---- -msc 0 - mgw remote-ip 10.9.8.7 - mgw remote-port 2427 +network + mgw 0 + remote-ip 10.9.8.7 + remote-port 2427 + reset-endpoint rtpbridge/* <1> +---- +<1> The 'reset-endpoint' setting instructs the OsmoBSC to send a wildcarded +DLCX to the media gateway. This helps to clear lingering calls from the +media gateway when the OsmoBSC is restarted. + +OsmoBSC is also able to handle a pool of media gateways for load +distribution since mid 2021. See also <<mgw_pooling>>. + +[NOTE] +==== +Previous versions of OsmoBSC didn't have the 'mgw' VTY node and +hence didn't support the MGW pooling feature. Therefore, historically the MGW +related commands where placed under the `msc` VTY node. The MGW related commands +under the `msc` VTY are still parsed and used but its use is deprecated and +hence discouraged in favour of the new `mgw` node. Writing the config to a file +from within OsmoBSC will automatically convert the config to use the new `mgw` +node. +==== + +===== Pinning a BTS to a specific MGW + +It is sometimes desirable to assign a specific MGW to a given BTS, so that all +calls where the BTS is involved use the assigned MGW with a higher precedence if +possible. + +This is specially important if the BTS is configured to serve calls using Osmux +instead of RTP. Osmux features trunking optimizations, which allow transmission +of audio payload from different concurrent calls inside the same underlaying UDP +packet, hence reducing the total required throughput and saving costs on the +required link. + +In order for Osmux trunking optimization to work, the source and destination IP +address of uderlaying UDP packet must be of course the same for all the calls +involved. That essentially boils down to having all the concurrent calls of the +BTS be connected to the same MGW so that they can be trunked over the same UDP +connection. + +The pinning to a specific MGW can be configured per BTS, and hence it is +configured under the `bts` VTY node: + +---- +OsmoBSC> enable +OsmoBSC# configure terminal +OsmoBSC(config)# network +OsmoBSC(config-net)# bts 1 +OsmoBSC(config-bts)# mgw pool-target 1 <1> +OsmoBSC(config-bts)# exit +OsmoBSC(config-net)# bts 2 +OsmoBSC(config-mgw)# mgw pool-target 7 strict <2> +OsmoBSC(config-net)# bts 3 +OsmoBSC(config-mgw)# no mgw pool-target <3> ---- + +<1> Pin BTS1 to prefer MGW1 (node `mgw 1`). If MGW1 is not configured, +administrateivly blocked or not connected at the time a new call is to be +established, then another MGW from the pool is selected following the usual +procedures. This allows applying pinning in the usual scenario while still +keeping call service ongoing against another MGW if the preferred MGW is not +available at a given time. + +<2> Pin BTS2 to prefer MGW7 (node `mgw 7`). If MGW7 is not configured, +administrateivly blocked or not connected at the time a new call is to be +established, then the MGW assignment will fail and ultimately the call will be +terminated during establishment. + +<3> Apply no pinning at all (default). The MGW with the lowest load is the one +being selected for each new call. + +==== Configure Lb to connect to an SMLC + +Enable the Lb interface. OsmoBSC will then use the default point-codes to +establish a connection to the SMLC. + +---- +smlc + enable +---- + +More detailed configuration is described in <<smlc-config>>. diff --git a/doc/manuals/chapters/smlc.adoc b/doc/manuals/chapters/smlc.adoc new file mode 100644 index 000000000..8bf33014d --- /dev/null +++ b/doc/manuals/chapters/smlc.adoc @@ -0,0 +1,90 @@ +== Location Services: Lb interface to SMLC + +OsmoBSC and OsmoSMLC support positioning by Timing-Advance (TA), since October +2020. + +A Perform Location Request is initiated by the MSC via BSSMAP on the +A-interface, for a specific subscriber. The request is typically passed on via +BSSMAP-LE on the Lb-interface to the SMLC. If required, the SMLC may request the +subscriber's Timing Advance (a.k.a. Access Delay) from the BSC via BSSLAP +(encapsulated BSSLAP APDU in a BSSMAP-LE Connection Oriented Information +message). The SMLC may combine several location and velocity estimate methods to +form a GAD PDU containing the resulting geographic location information. In +TA-based positioning, the Timing-Advance information from the BSC is combined +with the preconfigured latitude and longitude of the serving cell to form a +location estimate. This is returned to the BSC via the Lb-interface, and in turn +to the MSC via the A-interface. + +[mscgen] +---- +include::{srcdir}/message-sequences/location_services_ta.msc[] +---- + +Location Services (LCS) are described in 3GPP TS 43.059 <<3gpp-ts-43-059>>. +Messages for LCS on the A-interface (BSSMAP, between BSC and MSC) are described +in 3GPP TS 48.008 <<3gpp-ts-48-008>>, on the Lb-interface (BSSMAP-LE between BSC +and SMLC) in 3GPP TS 49.031 <<3gpp-ts-49-031>>. The resulting geographic +location and possibly velocity information is encoded in GAD, described in 3GPP +TS 23.032 <<3gpp-ts-23-032>>. + +[[smlc-config]] +=== Configure Lb-interface + +All Lb-interface related configuration is found in the `smlc` section of +OsmoBSC's configuration. + +By default, the Lb-interface is disabled in OsmoBSC. It is started by `enable`. + +---- +smlc + enable +---- + +On the Lb-interface, OsmoBSC always uses SSN "BSC (BSSMAP-LE)" (SSN code 250) +and contacts the remote SMLC on SSN "SMLC (BSSMAP-LE)" (SSN code 252). + +The point-codes are configurable, and default to OsmoBSC's local point-code +0.23.3 (187), and remote SMLC point-code 0.23.6 (190). + +Typically, multiple BSCs connect to the same SMLC, so that each BSC needs to +have a distinct point-code, while the SMLC has a single, fixed point-code. + +To configure a different remote SMLC point-code, first configure an arbitrarily +named SCCP address in the `cs7` address book, and then apply that to the +`smlc-addr` configuration: + +---- +cs7 instance 0 + sccp-address my-smlc + point-code 0.42.6 +smlc + enable + smlc-addr my-smlc +---- + +For the BSC side, it suffices to configure a point-code in the `cs7` section, +so that the BSC typically uses the same point-code on A and Lb interfaces. In +this example, the BSC has point-code `1.2.3` on the Lb interface: + +---- +cs7 instance 0 + point-code 1.2.3 +smlc + enable +---- + +It is also possible to configure a distinct BSC's point-code on Lb, using the +`bsc-addr` configuration. In the following example, the BSC uses point-code +`0.42.3` only on the Lb interface, while the A interface remains unchanged: + +---- +cs7 instance 0 + sccp-address my-bsc-on-lb + point-code 0.42.3 +smlc + enable + bsc-addr my-bsc-on-lb +---- + +The geographic locations of individual cells are configured at the SMLC. See +for example OsmoSMLC's user manual <<userman-osmosmlc>>. diff --git a/doc/manuals/chapters/smscb.adoc b/doc/manuals/chapters/smscb.adoc index 011aec413..6ac5370e6 100644 --- a/doc/manuals/chapters/smscb.adoc +++ b/doc/manuals/chapters/smscb.adoc @@ -102,3 +102,29 @@ OsmoBSC(config-cbc)# end ---- For more details on the available configuration commands, please check the OsmoBSC VTY Reference. + +=== Counters + +OsmoBSC has two Cell Broadcast related rate counter groups for each BTS: + +* the basic CBCH ("cell broadcast channel 0") +* the extended CBCH ("cell broadcast channel 1") + +See below example for a situation where no CBS messages were received yet from the CBC, +and hence only NULL messages have been sent on both basic and extended CBCH: + +.Example: CBCH related rate counters on a BTS that didn't receive any CBS messages +---- +cell broadcast channel 1: + cbch:rcvd_queued: 0 (0/s 0/m 0/h 0/d) Received + queued CBCH messages (Abis) + cbch:rcvd_dropped: 0 (0/s 0/m 0/h 0/d) Received + dropped CBCH messages (Abis) + cbch:sent_single: 0 (0/s 0/m 0/h 0/d) Sent single CBCH messages (Um) + cbch:sent_default: 0 (0/s 0/m 0/h 0/d) Sent default CBCH messages (Um) + cbch:sent_null: 31366 (0/s 45/m 2677/h 30588/d) Sent NULL CBCH messages (Um) +cell broadcast channel 0: + cbch:rcvd_queued: 0 (0/s 0/m 0/h 0/d) Received + queued CBCH messages (Abis) + cbch:rcvd_dropped: 0 (0/s 0/m 0/h 0/d) Received + dropped CBCH messages (Abis) + cbch:sent_single: 0 (0/s 0/m 0/h 0/d) Sent single CBCH messages (Um) + cbch:sent_default: 0 (0/s 0/m 0/h 0/d) Sent default CBCH messages (Um) + cbch:sent_null: 31366 (1/s 46/m 2676/h 30588/d) Sent NULL CBCH messages (Um) +---- diff --git a/doc/manuals/message-sequences/a_interface_bringup.msc b/doc/manuals/message-sequences/a_interface_bringup.msc new file mode 100644 index 000000000..165262167 --- /dev/null +++ b/doc/manuals/message-sequences/a_interface_bringup.msc @@ -0,0 +1,31 @@ +msc { + hscale=2; + bsc[label="BSC"], stp[label="STP"], _msc[label="MSC"]; + + |||; + ||| [label="We assume the MSC is already well connected to the STP and MGW(CN)"]; + + --- [label="SCTP/IP level establishment"]; + bsc =>> stp [label="SCTP INIT"]; + bsc <<= stp [label="SCTP INIT_ACK"]; + bsc =>> stp [label="SCTP COOKIE_ECHO"]; + bsc <<= stp [label="SCTP COOKIE_ACK"]; + ||| [label="SCTP payload can now be carried over the link"]; + |||; + |||; + --- [label="M3UA level establishment (over SCTP)"]; + bsc =>> stp [label="M3UA ASPUP"]; + bsc <<= stp [label="M3UA ASPUP_ACK"]; + bsc =>> stp [label="M3UA ASPAC (routing context)"]; + bsc <<= stp [label="M3UA ASPAC_ACK (routing context)"]; + bsc <<= stp [label="M3UA NTFY (AS-ACTIVE)"]; + ||| [label="M3UA payload can now be carried over the link"]; + |||; + --- [label="BSSMAP level establishment (over SCCP/M3UA/SCTP)"]; + bsc =>> _msc [label="BSSMAP RESET (OPC=BSC, DPC=MSC)"]; + bsc <<= _msc [label="BSSMAP RESET ACK (OPC=MSC, DPC=BSC)"]; + ||| [label="BSSMAP connection-oriented data can now be exchanged"]; + |||; + --- [label="Repeat BSSMAP level establishment (to other MSCs in the pool)"]; + |||; +} diff --git a/doc/manuals/message-sequences/location_services_ta.msc b/doc/manuals/message-sequences/location_services_ta.msc new file mode 100644 index 000000000..e6bef38ef --- /dev/null +++ b/doc/manuals/message-sequences/location_services_ta.msc @@ -0,0 +1,49 @@ +msc { + hscale="2"; + + ms[label="MS/BTS"],bsc[label="BSC"],smlc[label="SMLC"],__msc[label="MSC"]; + + ||| [label="Location Services (LCS): Perform Location Request using TA"]; + + |||; + --- [label="MS in DEDICATED MODE (currently active)"]; + + ms =>> bsc [label="earlier Measurement Report provides Timing Advance"]; + + bsc <<= __msc [label="PERFORM LOCATION REQUEST\n3GPP TS 48.008 3.2.1.71"]; + + bsc =>> smlc [label="BSSMAP-LE PERFORM LOCATION REQUEST\n3GPP TS 49.031 9.1\nwith BSSLAP APDU = TA Layer3\n3GPP TS 48.071 4.2.8"]; + + smlc rbox smlc [label="SMLC uses TA included in TA Layer3"]; + + bsc <<= smlc [label="BSSMAP-LE PERFORM LOCATION RESPONSE\n3GPP TS 49.031 9.2"]; + + bsc =>> __msc [label="PERFORM LOCATION RESPONSE\n3GPP TS 48.008 3.2.1.72"]; + + ...; + ...; + --- [label="MS in IDLE MODE (not connected)"]; + + bsc <<= __msc [label="PERFORM LOCATION REQUEST\n3GPP TS 48.008 3.2.1.71"]; + + bsc =>> smlc [label="BSSMAP-LE PERFORM LOCATION REQUEST\n3GPP TS 49.031 9.1"]; + + smlc rbox smlc [label="SMLC needs TA information,\nasks BSC via BSSLAP"]; + + bsc <<= smlc [label="BSSMAP-LE CONNECTION ORIENTED INFORMATION\n3GPP TS 49.031 9.12\nwith BSSLAP APDU = TA Request\n3GPP TS 48.071 4.2.1"]; + + + ms <<= bsc [label="RR Paging Request\n3GPP TS 48.018 9.1.22-24"]; + + ms =>> bsc [label="RSL CHANNEL REQUIRED\n3GPP TS 48.058 8.5.3\nincludes Access Delay (9.3.17) == Timing Advance"]; + + ms =>> bsc [label="RR Paging Response\n3GPP TS 48.018 9.1.25"]; + + ms <<= bsc [label="RF CHANNEL RELEASE\n3GPP TS 48.058 8.4.14"]; + + bsc =>> smlc [label="BSSMAP-LE CONNECTION ORIENTED INFORMATION\n3GPP TS 49.031 9.12\nwith BSSLAP APDU = TA Response\n3GPP TS 48.071 4.2.2"]; + + bsc <<= smlc [label="BSSMAP-LE PERFORM LOCATION RESPONSE\n3GPP TS 49.031 9.2"]; + + bsc =>> __msc [label="PERFORM LOCATION RESPONSE\n3GPP TS 48.008 3.2.1.72"]; +} diff --git a/doc/manuals/message-sequences/mo_call-abis_a.msc b/doc/manuals/message-sequences/mo_call-abis_a.msc index ba7f0aa18..2d988fcf3 100644 --- a/doc/manuals/message-sequences/mo_call-abis_a.msc +++ b/doc/manuals/message-sequences/mo_call-abis_a.msc @@ -85,8 +85,8 @@ linecolor="green"]; ...; --- [label="BSC finally can report successful TCH assignment"]; - bsc -> m_sc [label="SCCP DT1 (BSSMAP ASSGN CMPL (3GPP AoIP MGW:3000))"]; - m_sc box m_sc [label="Connect remote RTP to MGW addr from ASSGN CMPL"]; + bsc -> m_sc [label="SCCP DT1 (BSSMAP ASSIGN CMPL (3GPP AoIP MGW:3000))"]; + m_sc box m_sc [label="Connect remote RTP to MGW addr from ASSIGN CMPL"]; ...; mgw <-> m_sc [label="RTP Audio MGW:3000 MSC:4000", textcolor="blue", linecolor="blue"]; diff --git a/doc/manuals/message-sequences/mo_call-bsc-msc-mgw-aoip.msc b/doc/manuals/message-sequences/mo_call-bsc-msc-mgw-aoip.msc new file mode 100644 index 000000000..55fd6cd2f --- /dev/null +++ b/doc/manuals/message-sequences/mo_call-bsc-msc-mgw-aoip.msc @@ -0,0 +1,75 @@ +# MO-Call with OsmoBTS + OsmoBSC with true 3GPP AoIP +msc { + hscale=2; + ms [label="MS"], bts [label="OsmoBTS\n1.1.1.1"], bsc[label="OsmoBSC"], mgcp[label="OsmoMGW@BSC\n3.3.3.3"], m_sc[label="MSC"], mgw_m[label="MGW@MSC\n5.5.5.5"]; + + ms box m_sc [label="We assume a SDCCH is already established"]; + ...; + + ms -> m_sc [label="DTAP CC SETUP"]; + ms <- m_sc [label="DTAP CC CALL PROCEEDING"]; + + m_sc -> mgw_m [label="Request allocation of local RTP port"]; + m_sc <- mgw_m [label="Respond with RTP port the MGW bound to (5.5.5.5:4000)"]; + bsc <- m_sc [label="BSSAP ASSIGN REQ (3GPP AoIP, CN RTP IP/Port 5.5.5.5:4000)"]; + bts <- bsc [label="RSL CHAN ACT (TCH)"]; + bts -> bsc [label="RSL CHAN ACT ACK"]; + ms <-> bsc [label="RR Assignment of TCH"]; + ...; + + # connect BTS RTP with BSC-MGW RTP + bts <- bsc [label="IPA CRCX"]; + bts box bts [label="Bind to BTS-local RTP Port (1.1.1.1:1000)"]; + bts -> bsc [label="IPA CRCX ACK (1.1.1.1:1000)"]; + bsc -> mgcp [label="MGCP CRCX rtpbridge/2@mgw (1.1.1.1:1000)"]; + mgcp box mgcp [label="Bind to MGW-local RTP Port (3.3.3.3:2000)\nConnect to 1.1.1.1:1000"]; + bsc <- mgcp [label="MGCP CRCX rtpbridge/2@mgw OK (3.3.3.3:2000)"]; + bts <- bsc [label="IPA MDCX (3.3.3.3:2000)"]; + bts box bts [label="Connect RTP socket to remote (MGW) RTP Port"]; + bts -> bsc [label="IPA MDCX ACK"]; + bsc -> mgcp [label="MGCP MDCX rtpbridge/2@mgw (optional)"]; + bsc <- mgcp [label="MGCP MDCX rtpbridge/2@mgw OK (optional)"]; + ...; + + mgcp <- bsc [label="MGCP CRCX rtpbridge/2@mgw (5.5.5.5:4000)"]; + mgcp box mgcp [label="Bind to MGW-local RTP Port (3.3.3.3:3000)\nConnect to 5.5.5.5:4000"]; + mgcp -> bsc [label="MGCP CRCX rtpbridge/2@mgw OK (3.3.3.3:3000)"]; + ...; + + bsc -> m_sc [label="BSSAP ASSIGN CMPL (3GPP AoIP 3.3.3.3:3000)"]; + m_sc -> mgw_m [label="Request MGW to connect RTP to remote endpoint 3.3.3.3:3000"]; + mgw_m box mgw_m [label="Connect RTP to 3.3.3.3:3000"]; + ...; + + mgcp <=> mgw_m [label="RTP Audio 3.3.3.3:3000 5.5.5.5:4000"]; + bts <=> mgcp [label="RTP Audio 1.1.1.1:1000 3.3.3.3:2000"]; + ms <=> bts [label="Um Audio (bidirectional)"]; + ms <-> m_sc [label="DTAP CC ALERTING"]; + ...; + + ms <- m_sc [label="DTAP CC CONNECT"]; + ms -> m_sc [label="DTAP CC CONNECT ACK"]; + --- [label="Voice Call in Progress"]; + ms <- m_sc [label="DTAP CC DISCONNET"]; + ms <- m_sc [label="DTAP CC RELEASE"]; + ms <- m_sc [label="DTAP CC RELEASE COMPL"]; + ...; + bsc <- m_sc [label="BSSMAP CLEAR CMD"]; + m_sc -> mgw_m [label="Request release RTP port/termination"]; + mgw_m box mgw_m [label="Release RTP port 5.5.5.5:4000"]; + bsc -> m_sc [label="BSSMAP CLEAR COMPL"]; + bsc <- m_sc [label="SCCP RLSD"]; + bsc -> m_sc [label="SCCP RLC"]; + ...; + mgcp <- bsc [label="MGCP DLCX rtpbridge/2@mgw"]; + mgcp box mgcp [label="Release MSC-facing local RTP port (3.3.3.3:3000)"]; + mgcp -> bsc [label="MGCP DLCX rtpbridge/2@mgw OK"]; + + mgcp <- bsc [label="MGCP DLCX rtpbridge/2@mgw"]; + mgcp box mgcp [label="Release BTS-facing local RTP port (3.3.3.3:2000)"]; + mgcp -> bsc [label="MGCP DLCX rtpbridge/2@mgw OK"]; + + bts <- bsc [label="IPA DLCX"]; + bts box bts [label="Release BTS-local RTP port (1.1.1.1:1000)"]; + bts -> bsc [label="IPA DLCX OK"]; +} diff --git a/doc/manuals/mgw/classic-bsc.msc b/doc/manuals/mgw/classic-bsc.msc index 97b65131e..e2257298b 100644 --- a/doc/manuals/mgw/classic-bsc.msc +++ b/doc/manuals/mgw/classic-bsc.msc @@ -10,13 +10,13 @@ msc { ms -> m_sc [label="DTAP CC SETUP"]; ms <- m_sc [label="DTAP CC CALL PROCEEDING"]; - bsc <- m_sc [label="BSSAP ASSGN REQ"]; + bsc <- m_sc [label="BSSAP ASSIGN REQ"]; bsc box m_sc [label="E1 TS for PCM specified by CIC"]; bts <- bsc [label="RSL CHAN ACT"]; bts -> bsc [label="RSL CHAN ACT ACK"]; bts box bsc [label="E1 TS + 16k sub-slot configured for given lchan"]; ms <-> bsc [label="Assignment"]; - bsc -> m_sc [label="BSSAP ASSGN CMPL"]; + bsc -> m_sc [label="BSSAP ASSIGN CMPL"]; ...; trau <- m_sc [label="PCM Audio in full E1 slot"]; diff --git a/doc/manuals/mgw/osmo-bsc-new-mgw-e1.msc b/doc/manuals/mgw/osmo-bsc-new-mgw-e1.msc index 04b114fff..d58987f6d 100644 --- a/doc/manuals/mgw/osmo-bsc-new-mgw-e1.msc +++ b/doc/manuals/mgw/osmo-bsc-new-mgw-e1.msc @@ -1,8 +1,8 @@ # MO-Call with E1 BTS + OsmoBSC with true 3GPP AoIP (planned -# osmo-bsc_mgcp has to be extended to true MGW functionality! +# osmo-mgw has to be extended to true MGW functionality! msc { hscale=2; - ms [label="MS"], bts [label="E1 BTS"], bsc[label="OsmoBSC"], mgcp[label="osmo-bsc_mgcp"], m_sc[label="MSC"]; + ms [label="MS"], bts [label="E1 BTS"], bsc[label="OsmoBSC"], mgcp[label="osmo-mgw"], m_sc[label="MSC"]; ms box m_sc [label="We assume a SDCCH is already established"]; ...; @@ -11,7 +11,7 @@ msc { ms <- m_sc [label="DTAP CC CALL PROCEEDING"]; m_sc box m_sc [label="Bind arbitrary local port (4000)"]; - bsc <- m_sc [label="BSSAP ASSGN REQ (3GPP AoIP MSC:4000)"]; + bsc <- m_sc [label="BSSAP ASSIGN REQ (3GPP AoIP MSC:4000)"]; bts <- bsc [label="RSL CHAN ACT"]; bts -> bsc [label="RSL CHAN ACT ACK"]; ms <-> bsc [label="Assignment"]; @@ -22,8 +22,8 @@ msc { mgcp -> bsc [label="MGCP CRCX ts1/ss2@mgw OK (MGW:3000)"]; ...; - bsc -> m_sc [label="BSSAP ASSGN CMPL (3GPP AoIP MGW:3000)"]; - m_sc box m_sc [label="Connect remote RTP to MGW addr from ASSGN CMPL"]; + bsc -> m_sc [label="BSSAP ASSIGN CMPL (3GPP AoIP MGW:3000)"]; + m_sc box m_sc [label="Connect remote RTP to MGW addr from ASSIGN CMPL"]; ...; mgcp <=> m_sc [label="RTP Audio MGW:3000 MSC:4000"]; diff --git a/doc/manuals/mgw/osmo-bsc-new-mgw.msc b/doc/manuals/mgw/osmo-bsc-new-mgw.msc index e618bb721..d60a79f5e 100644 --- a/doc/manuals/mgw/osmo-bsc-new-mgw.msc +++ b/doc/manuals/mgw/osmo-bsc-new-mgw.msc @@ -1,7 +1,7 @@ -# MO-Call with OsmoBTS + OsmoBSC with true 3GPP AoIP (planned) +# MO-Call with OsmoBTS + OsmoBSC with true 3GPP AoIP msc { hscale=2; - ms [label="MS"], bts [label="OsmoBTS"], bsc[label="OsmoBSC"], mgcp[label="osmo-bsc_mgcp"], m_sc[label="MSC"]; + ms [label="MS"], bts [label="OsmoBTS"], bsc[label="OsmoBSC"], mgcp[label="OsmoMGW"], m_sc[label="MSC"]; ms box m_sc [label="We assume a SDCCH is already established"]; ...; @@ -10,7 +10,7 @@ msc { ms <- m_sc [label="DTAP CC CALL PROCEEDING"]; m_sc box m_sc [label="Bind arbitrary local port (4000)"]; - bsc <- m_sc [label="BSSAP ASSGN REQ (3GPP AoIP MSC:4000)"]; + bsc <- m_sc [label="BSSAP ASSIGN REQ (3GPP AoIP MSC:4000)"]; bts <- bsc [label="RSL CHAN ACT"]; bts -> bsc [label="RSL CHAN ACT ACK"]; ms <-> bsc [label="Assignment"]; @@ -35,8 +35,8 @@ msc { mgcp -> bsc [label="MGCP CRCX rtpbridge/2@mgw OK (MGW:3000)"]; ...; - bsc -> m_sc [label="BSSAP ASSGN CMPL (3GPP AoIP MGW:3000)"]; - m_sc box m_sc [label="Connect remote RTP to MGW addr from ASSGN CMPL"]; + bsc -> m_sc [label="BSSAP ASSIGN CMPL (3GPP AoIP MGW:3000)"]; + m_sc box m_sc [label="Connect remote RTP to MGW addr from ASSIGN CMPL"]; ...; mgcp <=> m_sc [label="RTP Audio MGW:3000 MSC:4000"]; diff --git a/doc/manuals/mgw/osmo-bsc-old-sccplite.msc b/doc/manuals/mgw/osmo-bsc-old-sccplite.msc index 067721c46..cd6cd648c 100644 --- a/doc/manuals/mgw/osmo-bsc-old-sccplite.msc +++ b/doc/manuals/mgw/osmo-bsc-old-sccplite.msc @@ -10,11 +10,11 @@ msc { ms -> m_sc [label="DTAP CC SETUP"]; ms <- m_sc [label="DTAP CC CALL PROCEEDING"]; - bsc <- m_sc [label="BSSAP ASSGN REQ"]; + bsc <- m_sc [label="BSSAP ASSIGN REQ"]; bts <- bsc [label="RSL CHAN ACT"]; bts -> bsc [label="RSL CHAN ACT ACK"]; ms <-> bsc [label="Assignment"]; - bsc -> m_sc [label="BSSAP ASSGN CMPL"]; + bsc -> m_sc [label="BSSAP ASSIGN CMPL"]; ...; bts <- bsc [label="IPA CRCX"]; diff --git a/doc/manuals/osmobsc-cbsp-docinfo.xml b/doc/manuals/osmobsc-cbsp-docinfo.xml new file mode 100644 index 000000000..a86fd286e --- /dev/null +++ b/doc/manuals/osmobsc-cbsp-docinfo.xml @@ -0,0 +1,36 @@ + +<authorgroup> + <author> + <firstname>Harald</firstname> + <surname>Welte</surname> + <email>hwelte@sysmocom.de</email> + <authorinitials>HW</authorinitials> + <affiliation> + <shortaffil>sysmocom</shortaffil> + <orgname>sysmocom - s.f.m.c. GmbH</orgname> + <jobtitle>Managing Director</jobtitle> + </affiliation> + </author> +</authorgroup> + +<copyright> + <year>2022</year> + <holder>sysmocom - s.f.m.c. GmbH</holder> +</copyright> + +<legalnotice> + <para> + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with no Invariant Sections, no Front-Cover Texts, + and no Back-Cover Texts. A copy of the license is included in + the section entitled "GNU Free Documentation License". + </para> + <para> + The Asciidoc source code of this manual can be found at + <ulink url="https://git.osmocom.org/osmo-bsc/"> + https://git.osmocom.org/osmo-bsc/ + </ulink> + </para> +</legalnotice> diff --git a/doc/manuals/osmobsc-cbsp.adoc b/doc/manuals/osmobsc-cbsp.adoc new file mode 100644 index 000000000..89af8dfcc --- /dev/null +++ b/doc/manuals/osmobsc-cbsp.adoc @@ -0,0 +1,69 @@ +:gfdl-enabled: + +OsmoBSC CBSP Protocol Specification +=================================== +Harald Welte <hwelte@sysmocom.de> + +== Introduction + +This document describes the CBSP interface of *OsmoBSC* as spoken on the +BSC-CBC interface. Based on 3GPP TS 48.049 <<3gpp-ts-48-049>>, this document indicates +which of the 3GPP specified CBSP messages and IEs are implemented +according to 3GPP specifications, which of these are not or not fully +implemented, as well as OsmoBSC-specific extensions to the CBSP +interface not specified by 3GPP. + +For details on the standard CBSP messages and IE definitions, +please refer to the 3GPP documents. + +.3GPP document versions referred to by this document +[cols="20%,80%"] +|=== +|3GPP TS 48.049 | version 12.0.0 Release 12 +|=== + +.IETF documents referred to by his document +[cols="20%,80%"] +|=== +|IETF RFC 793 | Transmission Control Protocol +|=== + +== Overview + +The OsmoBSC BSC-CBC interface consists of CBSP messages transmitted over +TCP. + +The default TCP destination port number is TCP port 48049; this can be +changed by configuration, as described in the OsmoBSC user manual +<<userman-osmobsc>> and/or VTY reference manual <<vty-ref-osmobsc>>. + +.TCP port numbers used by OsmoBTS Abis/IP +[options="header",width="50%",cols="35%,65%"] +|=== +|TCP Port Number|Usage +|48049|CBSP +|=== + +OsmoBSC implements both _TCP server_ and _TCP client_ role; it is hence +configurable whether the CBC establishes the TCP connection to the BSC +(BSC in _TCP server_ role) or if the BSC establishes the TCP connection +to the CBC (BSC in _TCP client_ role). + +Currently, only transport of TCP via IPv4 is implemented. + +Any IP-capable link-layer protocol implemented in the underlying Linux +operating system can be used to transport the IP/TCP/CBSP of OsmoBSC. + + +include::{srcdir}/cbsp/procedures.adoc[] + +include::{srcdir}/cbsp/messages.adoc[] + + +include::./common/chapters/port_numbers.adoc[] + +include::./common/chapters/bibliography.adoc[] + +include::./common/chapters/glossary.adoc[] + +include::./common/chapters/gfdl.adoc[] diff --git a/doc/manuals/osmobsc-usermanual.adoc b/doc/manuals/osmobsc-usermanual.adoc index a34d3d422..2e77e1b5f 100644 --- a/doc/manuals/osmobsc-usermanual.adoc +++ b/doc/manuals/osmobsc-usermanual.adoc @@ -24,12 +24,24 @@ include::{srcdir}/chapters/bts-examples.adoc[] include::{srcdir}/chapters/bsc.adoc[] +include::{srcdir}/chapters/chan_alloc.adoc[] + +include::{srcdir}/chapters/power_control.adoc[] + +include::{srcdir}/chapters/interf_meas.adoc[] + include::{srcdir}/chapters/handover.adoc[] include::{srcdir}/chapters/smscb.adoc[] include::{srcdir}/chapters/mscpool.adoc[] +include::./common/chapters/mgwpool.adoc[] + +include::{srcdir}/chapters/smlc.adoc[] + +include::./common/chapters/qos-dscp-pcp.adoc[] + include::./common/chapters/counters-overview.adoc[] include::{srcdir}/chapters/counters.adoc[] @@ -44,6 +56,8 @@ include::{srcdir}/chapters/osmux_bsc.adoc[] include::./common/chapters/vty_cpu_sched.adoc[] +include::{srcdir}/chapters/aoip-flows.adoc[] + include::./common/chapters/port_numbers.adoc[] include::./common/chapters/bibliography.adoc[] |