[[control]]
== Control interface

The actual protocol is described in <<common-control-if>>, the variables
common to all programs using it are described in <<ctrl_common_vars>>. Here we
describe variables specific to OsmoBSC. The commands starting with prefix
"bts.N." are specific to a certain BTS so N have to be replaced with BTS
number when issuing command e. g. "bts.1.channel-load". Similarly the
TRX-specific commands are additionally prefixed with TRX number e. g.
"bts.1.trx.2.arfcn".

.Variables available over control interface
[options="header",width="100%",cols="20%,5%,5%,50%,20%"]
|===
|Name|Access|Trap|Value|Comment
|msc_connection_status|RO|Yes|"connected", "disconnected"|Indicate the status of connection to MSC.
|bts_connection_status|RO|Yes|"connected", "disconnected"|Indicate the status of connection to BTS.
|location|RW|Yes|"<unixtime>,(invalid\|fix2d\|fix3d),<lat>,<lon>,<height>"|Set/Get location data.
|timezone|RW|No|"<hours>,<mins>,<dst>", "off"|-19 \<= hours \<= 19, mins in {0, 15, 30, 45}, and 0 \<= dst \<= 2
|apply-configuration|WO|No|"restart"|Restart all BTSes.
|mnc|RW|No|"<mnc>"|Set/Get MNC (value between (0, 999)).
|mcc|RW|No|"<mcc>"|Set/Get MCC (value between (1, 999)).
|mcc-mnc-apply|WO|No|"<mcc>,<mnc>"|Apply new MCC/MNC values if different from currently used one.
|notification|WO|Yes|Arbitrary value| See <<notif>> for details.
|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.bsic|RW|No|"<bsic>"|Set/Get BSIC (value between (0, 63)).
|bts.N.rach-max-delay|RW|No|"<delay>"|Set/Get RACH max delay (value between (1, 127)).
|bts.N.apply-configuration|WO|No|Ignored|Restart BTS via OML.
|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.
|bts.N.gprs-mode|RW|No|"<mode>"|See <<gprsm>> for details.
|bts.N.rf_state|RO|No|"<oper>,<admin>,<pol>"|See <<rfs>> for details.
|bts.N.cell-reselection-offset|RW|No|"<cro>"|Set/Get cell reselection offset (value between (0, 126), steps of 2).
|bts.N.cell-reselection-penalty-time|RW|No|"<penalty-time>","reserved"|Set/Get cell reselection penalty time (value between (20, 620), steps of 20).
|bts.N.cell-reselection-hysteresis|RW|No|"<crh>"|Set/Get cell reselection hysteresis (value between (0, 14), steps of 2).
|bts.N.rach-access-control-classes|RO|No|"<class>,(barred|allowed)"|Get concatenated pairs of RACH access control classes.
|bts.N.rach-access-control-class.bar|WO|No|"<class>","emergency"|Set RACH access control class as barred.
|bts.N.rach-access-control-class.allow|WO|No|"<class>","emergency"|Set RACH access control class as allowed.
|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.
|bts.N.neighbor-list.si5-add|WO|No|<0-1023>|Add to manual SI5 neighbor list.
|bts.N.neighbor-list.si5-del|WO|No|<0-1023>|Delete from manual SI5 neighbor list.
|bts.N.neighbor-list.si2|RO|No|"<arfcn>"|Get space concatenated list of SI2 neighbor ARFCNs.
|bts.N.neighbor-list.si5|RO|No|"<arfcn>"|Get space concatenated list of SI5 neighbor ARFCNs.
|bts.N.neighbor-list.si2quater.uarfcns|RO|No|"<uarfcn>,<scrambling code>,<diversity bit>"|Get space concatenated list of UARFCN neighbors.
|bts.N.neighbor-list.si2quater.earfcns|RO|No|"<earfcn>,<thresh-hi>,<thresh-lo>,<prio>,<qrxlv>,<meas>"|Get space concatenated list of EARFCN neighbors.
|bts.N.si2quater-neighbor-list.add.uarfcn|WO|No|"<uarfcn>,<scrambling code>,<diversity bit>"|Add UARFCN neighbor.
|bts.N.si2quater-neighbor-list.del.uarfcn|WO|No|"<uarfcn>,<scrambling code>"|Delete UARFCN neighbor.
|bts.N.si2quater-neighbor-list.add.earfcn|WO|No|"<earfcn>,<thresh-hi>,<thresh-lo>,<prio>,<qrxlv>,<meas>"|Add EARFCN neighbor.
|bts.N.si2quater-neighbor-list.del.earfcn|WO|No|"<earfcn>"|Delete EARFCN neighbor (value between (0, 65535)).
|===

[[notif]]
=== notification

Setting this variable initiate TRAP "notification" to all the clients connected
to control interface with the value supplied in SET operation. This is not
intended to be used outside of local systems.

[[infomsc]]
=== inform-msc-v1

Setting this variable initiate TRAP "inform-msc-v1" to all connected MSCs 
control interfaces with the value supplied in SET operation.

[[chanlo]]
=== channel-load

Obtain channel load for given BTS. Returns concatenated set of triplets
("<name>,<used>,<total>") for all channel types configured on the BTS. The
"<name>" is the channel type. The "<used>" is the number of channels of that
type currently in use. The "<total>" is the number of channels of that type
configured on the BTS.

[[gprsm]]
=== gprs-mode

Set/Get the GPRS mode of the BTS. One of the following is
accepted/returned: "none", "gprs", "egprs".

[[rfs]]
=== rf_state

Following triplet is returned: "<oper>,<admin>,<pol>". The "<oper>" might be
"operational" or "inoperational" representing different operational states. The
"<admin>" might be "locked" or "unlocked" representing administrative status.
The "<pol>" might be "off", "on", "grace" or "unknown" representing different
RF policies.

[[rfl]]
=== rf_locked

Set/Get RF locked status. The GET operation will return either "0" or "1"
depending on the RF lock status. The SET operation will set  RF lock status if
RF Ctrl is enabled in the BSC Configuration.

[[mpr]]
=== max-power-reduction

Set/Get the value of maximum power reduction. Even values between 0 and 22 are
accepted.

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