== 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 <> 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 <> for further information. *-T, --timestamp*:: Enable time-stamping of log messages to stderr. This has mostly been deprecated by VTY based logging configuration, see <> 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 <> 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 <> 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_ <>. 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 23 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 ----