== BTS Configuration

The role of the BTS is to handle the GSM radio interface.  When the BTS
application is starting, the A-bis OML connection is established towards
the BSC.  Almost all BTS configuration (such as ARFCN, channel
configuration, transmit power, etc.) will be sent from the BSC to the
BTS via OML messages.  After OML start-up has completed, the BSC will
instruct the BTS to establish the RSL connections.

Given that most configuration is downloaded from the BSC into the BTS at
start-up time, only some very basic settings have to be made in the
OsmoBTS software.


=== Command Line Options

The OsmoBTS executables (`osmo-bts-sysmo`, `osmo-bts-trx`,
`osmo-bts-octphy`, `osmo-bts-litecell15`, ...) share the following
generic command line options:

==== SYNOPSIS
*osmo-bts-sysmo* [-h|-V] [-d 'DBGMASK'] [-D] [-c 'CONFIGFILE' ] [-s] [-T] [-e 'LOGLEVEL']

==== OPTIONS
*-h, --help*::
	Print a short help message about the supported options
*-V, --version*::
	Print the compile-time version number of the OsmoBTS program
*-d, --debug 'DBGMASK','DBGLEVELS'*::
	Set the log subsystems and levels for logging to stderr. This
	has mostly been superseded by VTY-based logging configuration,
	see <<logging>> for further information.
*-D, --daemonize*::
	Fork the process as a daemon into background.
*-c, --config-file 'CONFIGFILE'*::
	Specify the file and path name of the configuration file to be
	used. If none is specified, use `osmo-bts.cfg` in the current
	working directory.
*-s, --disable-color*::
	Disable colors for logging to stderr. This has mostly been
	deprecated by VTY based logging configuration, see <<logging>>
	for further information.
*-T, --timestamp*::
	Enable time-stamping of log messages to stderr. This has mostly
	been deprecated by VTY based logging configuration, see
	<<logging>> for further information.
*-e, --log-level 'LOGLEVEL'*::
	Set the global log level for logging to stderr. This has mostly
	been deprecated by VTY based logging configuration, see
	<<logging>> for further information.

There may be additional, hardware specific command line options by the
different bts_model implementations.


=== Configuration using the VTY

Most configuration as well as run-time monitoring and system
introspection is implemented using a command-line based interface
called _VTY_. A full reference syntax of all existing VTY command is
available as a separate document.

See <<vty>> for further information on the VTY.


==== Required BTS/TRX configuration

There are some settings that have to be configured locally in the
sysmoBTS, as they cannot be set remotely from the BSC. Those
settings are stored in the OsmoBTS configuration file, which commonly
is stored in `/etc/osmocom/osmo-bts.cfg`.

.Example Minimal configuration file
----
!
! OsmoBTS (0.0.1.100-0455) configuration saved from vty
!!
!
phy 0 <1>
 instance 0 <2>
bts 0 <3>
 band DCS1800
 ipa unit-id 1801 0 <4>
 oml remote-ip 192.168.100.11 <5>
 trx 0 <6>
  phy 0 instance 0 <7>
----
<1> You must configure at least one PHY link by means of the PHY node
<2> You must configure at least one PHY instance in the PHY link
<3> There is always exactly one BTS (`bts 0`) configured in OsmoBTS
<4> The `ipa unit-id` is what is used to identify this BTS to the BSC
<5> The OML Remote IP is the IP address of the BSC, to which the BTS shall connect to.
<6> There must be at least one trx (`trx 0`) in each BTS
<7> Every TRX must be mapped to a specific PHY instance this way

For a full reference of all available VTY configuration parameters,
please refer to the OsmoBTS VTY Reference document.

[[gsmtap]]
==== Configuring GSMTAP tracing

In addition to being able to obtain pcap protocol traces of the A-bis
communication and the text-based logging from the OsmoBTS
software, there is also the capability of tracing all communication on
the radio interface. To do so, OsmoBTS can encapsulate
MAC blocks (23byte messages at the L2-L1 interface) into _GSMTAP_ and send
them via UDP/IP. At that point, they can be captured with utilities like
*tcpdump* or *tshark* for further analysis by the *wireshark* protocol
analyzer.

In order to activate this feature, you first need to make sure to specify
the remote address of _GSMTAP_ host in the configuration file.  In most
cases, using 127.0.0.1 for passing the messages over the loopback (`lo`)
device will be sufficient:

.Example: Enabling GSMTAP Um-frame logging to localhost
----
bts 0
 gsmtap-remote-host 127.0.0.1 <1>
----
<1> Destination address for _GSMTAP_ Um-frames

NOTE: Changing this parameter at run-time will not affect the existing
_GSMTAP_ connection, full program restart is required.

NOTE: Command line parameters `-i` and `--gsmtap-ip` have been deprecated.

OsmoBTS can selectively trace such messages by their L1 SAPI, for both
Rx and Tx. For a complete list of L1 SAPI values, please refer to the
_OsmoBTS VTY reference manual_ <<vty-ref-osmobts>>.

For example, to enable GSMTAP tracing for messages on all SDCCH
channels, you can use the gsmtap-sapi sdcch command at the CONFIG TRX
node of the OsmoBTS VTY.

.Example: Enabling  GSMTAP for SDCCH
----
OsmoBTS> enable
OsmoBTS# configure terminal
OsmoBTS(config)# bts 0
OsmoBTS(bts)# gsmtap-sapi sdcch
OsmoBTS(trx)# write <1>
----
<1> the `write` command will make the configuration persistent in the
configuration file.  This is not required if you wish to enable GSMTAP
only in the current session of OsmoBTS.

De-activation can be performed similarly by using the `no gsmtap-sapi
sdcch` command at the `bts` node of the OsmoBTS VTY.

It may be useful to enable all SAPIs with a few exceptions, or vice versa
disable everything using one command.  For this purpose, the VTY provides
`gsmtap-sapi enable-all` and `gsmtap-sapi disable-all` commands.

.Example: Enabling all SAPIs except PDTCH and PTCCH
----
bts 0
 gsmtap-sapi enable-all <1>
 no gsmtap-sapi pdtch <2>
 no gsmtap-sapi ptcch <2>
----
<1> Enable all available SAPIs
<2> Exclude PDTCH and PTCCH SAPIs

From the moment they are enabled via VTY, GSMTAP messages will be
generated and sent in UDP encapsulation to the IANA-registered UDP port
for GSMTAP (4729) of the specified remote address.

==== Configuring power ramping

OsmoBTS can ramp up the power of its trx over time. This helps reduce
cell congestion in busy environments.

Some models of OsmoBTS (such as osmo-bts-trx) also support ramping down the
transmit power over time until finally ceasing broadcast, for instance due to a
trx becoming administratively locked or due to the whole BTS being gracefully
shut down. This allows for mobile stations camping on the cell to gradually move
to other cells in the area once the signal drop is detected.

In this example, the trx starts with 5dBm output power which increases by 1dB
every two seconds until it reaches nominal power.
Power ramping can use the power-ramp commands at the CONFIG TRX node of the
OsmoBTS VTY.

.Example: Configure power ramping on trx 0
----
OsmoBTS> enable
OsmoBTS# configure terminal
OsmoBTS(config)# bts 0
OsmoBTS(bts)# trx 0
OsmoBTS(trx)# power-ramp max-initial 5 dBm
OsmoBTS(trx)# power-ramp step-size 1 dB
OsmoBTS(trx)# power-ramp step-interval 2
OsmoBTS(trx)# write <1>
----
<1> the `write` command will make the configuration persistent in the
configuration file.

De-activating power-ramping can be performed by setting the max-initial value
to the nominal power. The default max-initial value is 0 dBm.


==== Running multiple instances

It is possible to run multiple instances of `osmo-bts` on one and the same
machine, if the phy-interface is flexible enough to distinguish between
different phy hardware interfaces.

Since usually a BTS instance runs in conjunction with a dedicated PCU instance,
the socket path between PCU and BTS has to be distinguished between the running
instances. It is possible to change the default socket path via VTY config:

.Example: Personalize PCU socket path
----
bts 0
 pcu-socket /tmp/pcu_bts_2
----

It is also necessary to separate the VTY anc CTRL interfaces of the different
instances. The VTY, as well as the CTRL interface can be bound to a free IP
address from the loopback range:

.Example: Binding VTY and CTRL interface to a specific IP address
----
line vty
 bind 127.0.0.2
ctrl
 bind 127.0.0.2
----
