== 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.
