diff options
Diffstat (limited to 'doc/manuals/chapters')
| -rw-r--r-- | doc/manuals/chapters/architecture.adoc | 120 | ||||
| -rw-r--r-- | doc/manuals/chapters/bts-models.adoc | 441 | ||||
| -rw-r--r-- | doc/manuals/chapters/configuration.adoc | 210 | ||||
| -rw-r--r-- | doc/manuals/chapters/control.adoc | 24 | ||||
| -rw-r--r-- | doc/manuals/chapters/dynamic-timeslots.adoc | 20 | ||||
| -rw-r--r-- | doc/manuals/chapters/interfaces.adoc | 156 | ||||
| -rw-r--r-- | doc/manuals/chapters/overview.adoc | 105 |
7 files changed, 1076 insertions, 0 deletions
diff --git a/doc/manuals/chapters/architecture.adoc b/doc/manuals/chapters/architecture.adoc new file mode 100644 index 00000000..a0e66cd0 --- /dev/null +++ b/doc/manuals/chapters/architecture.adoc @@ -0,0 +1,120 @@ +== OsmoBTS software architecture + +=== OsmoBTS PHY interface abstraction + +The OsmoBTS PHY interface serves as an internal abstraction layer +between given PHY hardware (as provided by the bts_model) and the actual +logical transceivers (TRXs) of a BTS inside the OsmoBTS code base. + + +==== PHY link + +A PHY link is a physical connection / link towards a given PHY. This +might be, for example, + +* a set of file descriptors to device nodes in the /dev/ directory + (sysmobts, litecell15) +* a packet socket for sending raw Ethernet frames to an OCTPHY +* a set of UDP sockets for interacting with OsmoTRX + +Each PHY interface has a set of attribute/parameters and a list of 1 to +n PHY instances. + +PHY links are numbered 0..n globally inside OsmoBTS. + +Each PHY link is configured via the VTY using its individual top-level +vty node. Given the different bts-model / phy specific properties, the +VTY configuration options (if any) of the PHY instance differ between +BTS models. + +The PHY links and instances must be configured above the BTS/TRX nodes +in the configuration file. If the file is saved via the VTY, the code +automatically ensures this. + + +==== PHY instance + +A PHY instance is an instance of a PHY, accessed via a PHY link. + +In the case of osmo-bts-sysmo and osmo-bts-trx, there is only one +instance in every PHY link. This is due to the fact that the API inside +that PHY link does not permit for distinguishing multiple different +logical TRXs. + +Other PHY implementations like the OCTPHY however do support addressing +multiple PHY instances via a single PHY link. + +PHY instances are numbered 0..n inside each PHY link. + +Each PHY instance is configured via the VTY as a separate node beneath each +PHY link. Given the different bts-model / phy specific properties, the +VTY configuration options (if any) of the PHY instance differ between +BTS models. + + +==== Mapping PHY instances to TRXs + +Each TRX node in the VTY must use the 'phy N instance M' command in +order to specify which PHY instance is allocated to this specific TRX. + +=== Internal control flow + +==== start-up / sequencing during OsmoBTS start + +.Control flow at OsmoBTS start-up procedure +[options="header",cols="10%,35%,55%"] +|=== +| section | function | description +| bts-specific | main() | Entering main() from glibc +| common | bts_main() | initialization of talloc contexts +| common | bts_log_init() | initialization of logging +| common | handle_options() | common option parsing +| bts-specific | bts_model_handle_options() | model-specific option parsing +| common | gsm_bts_alloc() | allocation of BTS/TRX/TS data structures +| common | vty_init() | Initialziation of VTY core, libosmo-abis and osmo-bts VTY +| common | main() | Setting of scheduler RR priority (if configured) +| common | main() | Initialization of GSMTAP (if configured) +| common | bts_init() | configuration of defaults in bts/trx/s object +| bts-specific | bts_model_init | ? +| common | abis_init() | Initialization of libosmo-abis +| common | vty_read_config_file() | Reading of configuration file +| bts-specific | bts_model_phy_link_set_defaults() | Called for every PHY link created +| bts-specific | bts_model_phy_instance_set_defaults() | Called for every PHY Instance created +| common | bts_controlif_setup() | Initialization of Control Interface +| bts-specific | bts_model_ctrl_cmds_install() | Install model-specific control interface commands +| common | telnet_init() | Initialization of telnet interface +| common | pcu_sock_init() | Initialization of PCU socket +| common | main() | Installation of signal handlers +| common | abis_open() | Start of the A-bis connection to BSC +| common | phy_links_open() | Iterate over list of configured PHY links +| bts-specific | bts_model_phy_link_open() | Open each of the configured PHY links +| common | write_pid_file() | Generate the pid file +| common | osmo_daemonize() | Fork as daemon in background (if configured) +| common | bts_main() | Run main loop until global variable quit >= 2 +|=== + + +==== At time of OML establishment + +.Control flow at time of OML establishment +[options="header",cols="10%,35%,55%"] +|=== +| section | function | description +| bts-specific | bts_model_oml_estab() | Called by core once OML link is established +| bts-specific | bts_model_check_oml() | called each time OML sets some attributes on a MO, checks if attributes are valid +| bts-specific | bts_model_apply_oml() | called each time OML sets some attributes on a MO, stores attribute contents in data structures +| bts-specific | bts_model_opstart() | for NM_OC_BTS, NM_OC_SITE_MANAGER, NM_OC_GPRS_NSE, NM_OC_GPRS_CELL, NMO_OC_GPRS_NSVC +| bts-specific | bts_model_opstart() | for NM_OC_RADIO_CARRIER for each trx +| bts-specific | bts_model_opstart() | for NM_OC_BASEB_TRANSC for each trx +| bts-specific | bts_model_opstart() | for NM_OC_CHANNEL for each timeslot on each trx +| bts-specific | bts_model_change_power() | change transmit power for each trx (power ramp-up/ramp-down) +|=== + +==== At time of RSL connection loss + +.Control flow at time of RSL connection loss +[options="header",cols="10%,35%,55%"] +|=== +| section | function | description +| bts-specific | bts_model_abis_close() | called when either one of the RSL links or the OML link are down +|=== diff --git a/doc/manuals/chapters/bts-models.adoc b/doc/manuals/chapters/bts-models.adoc new file mode 100644 index 00000000..4ae73c0b --- /dev/null +++ b/doc/manuals/chapters/bts-models.adoc @@ -0,0 +1,441 @@ +[[osmobts_hardware_support]] +== OsmoBTS hardware support + +OsmoBTS consists of a _common_ part that applies to all BTS models as well as +_hardware-specific_ parts for each BTS model. The hardware specific parts are +generally referred to as the _bts_model_ code. + +The common part includes the core BTS architecture as well as code for +implementing the external interfaces such as Abis, control, PCU socket and +GSMTAP. + +The bts_model parts include support for driving one particular +implementation of a GSM physical layer (PHY). Such a physical layer +implementation can come in many forms. Sometimes it runs on a general +purpose CPU, sometimes on a dedicated ARM core, a dedicated DSP, a +combination of DSP and FPGA. + +Every PHY implementation offers some kind of primitives by which the PHY +can be controlled, and by which the PHY exchanges data with the higher +layers of the protocol stack in the OsmoBTS code. + +The PHY-specific primitives are encapsulated in the bts_model code, and +offered as a PHY-independent _L1SAP_ interface towards the common part of +OsmoBTS. + +In addition, each bts_model implements a set of functions that the +common part calls. Those functions are pre-fixed by _bts_model__. + +Each bts_model may offer + +* model-specific VTY commands for both configuration and run-time interaction +* model-specific command line arguments +* model-specific control interface commands + +== `osmo-bts-sysmo` for sysmocom sysmoBTS + +The sysmocom sysmoBTS is a range of GSM BTSs based around an embedded +system implementing the PHY in a combination of DSP+FPGA. The PHY is +configured by a set of primitives described by header files. Those +primitives are exchanged over a set of message queues exposed on the +Linux-running ARM core via device nodes in `/dev/msgq/`. Internally, +the message queues map to shared memory between the Linux-running ARM +core and the DSP running the PHY implementation. + +The OsmoBTS bts_model code for the sysmoBTS can be found in the +`src/osmo-bts-sysmo` sub-directory of the OsmoBTS code base. + +`osmo-bts-sysmo` has been the primary target platform for +OsmoBTS for many years and is thus the most feature-complete and mature +platform supported by OsmoBTS at this point. + +The sysmoBTS PHY supports a direct PHY interface to OsmoPCU, reducing +the latency and amount of primitives that OsmoBTS would otherwise need +to pass through from the PHY message queues to the PCU socket and +vice-versa. + + +=== `osmo-bts-sysmo` specific command line arguments + +*--dsp-trace 'DSPMASK'*:: + Set the DSP trace flags (a single hexadecimal 32bit value). + This has been deprecated by VTY based commands, see + <<osmo-bts-sysmo-dsp-trace>> for further information. +*--pcu-direct*:: + Indicate that an external PCU (e.g. OsmoPCU) will directly + open the DSP message queues to the PHY / PH-SAP, and only MPH + primitives are passed via OsmoBTS. + + +=== `osmo-bts-sysmo` specific VTY commands + +For a auto-generated complete syntax reference of the VTY commands, +please see the associated _OsmoBTS VTY reference manual_ +<<vty-ref-osmobts>>. The section +below only lists the most important commands. + +==== at the 'SHOW' node + +===== `show trx 0 clock-source` + +Display the currently active clock source configuration for the TRX + +[[osmo-bts-sysmo-dsp-trace]] +===== `show trx 0 dsp-trace-flags` + +Show the currently active DSP trace flags for the TRX + +===== `trx 0 dsp-trace-flag` + +Use this command to enable/disable/configure the DSP tracing flags that +define what debug messages will appear on `/dev/rtfifo/dsp_trace`. + +==== at the 'ENABLE' node + +===== `trx 0 tx-power <-110-100>` + +Change the current TRX transmit power to the given value in dBm. + +===== `trx 0 rf-clock-info reset` + +Part of the clock calibration procedure: +Reset the clock correction value. + +===== `trx 0 rf-clock-info correct` + +Part of the clock calibration procedure: +Apply the current measured correction value between the reference clock +and the local clock. + +==== at the 'PHY instance' node + +==== `clock-calibration eeprom` + +Obtain clock calibration value from EEPROM. + +==== `clock-calibration default` + +Use hardware default clock calibration value. + +==== `clock-calibration <-4095-4095>` + +Use specified clock calibration value (not EEPROM/default). + +==== `clock-source (tcxo|ocxo|ext|gps)` + +Specify the clock source for the PHY: + +tcxo:: + Use the TCXO. This is the default on sysmoBTS 2050. +ocxo:: + Use the OCXO (only valid on units equipped with OCXO). This is + the default on all sysmoBTS 1002/1020/1100 and SOB-BTS. +ext:: + Use the external clock input. +gps:: + Use the clock derived from GPS. You shouldn't use this clock + directly, but rather use the TCXO and regularly re-calibrate + against GPS. + +==== `trx-calibration-path PATH` + +Use calibration files from the given 'PATH', rather tan calibration +values from the EEPROM. + +=== `osmo-bts-sysmo` specific control interface commands + +==== trx.0.clock-info + +Obtain information on the current clock status: + +---- +bsc_control.py -d localhost -p 4238 -g trx.0.clock-info +Got message: GET_REPLY 1 trx.0.clock-info -100,ocxo,0,0,gps +---- + +which is to be interpreted as: + +* current clock correction value is -100 ppb +* current clock source is OCXO +* deviation between clock source and calibration source is 0 ppb +* resolution of clock error measurement is 0 ppt (0 means no result yet) +* current calibration source is GPS + +When this attribute is set, any value passed on is discarded, but the clock +calibration process is re-started. + +==== trx.0.clock-correction + +This attribute can get and set the current clock correction value: + +---- +bsc_control.py -d localhost -p 4238 -g trx.0.clock-correction +Got message: GET_REPLY 1 trx.0.clock-correction -100 +---- + +---- +bsc_control.py -d localhost -p 4238 -s trx.0.clock-correction -- -99 +Got message: SET_REPLY 1 trx.0.clock-correction success +---- + + +== `osmo-bts-trx` for OsmoTRX + +OsmoTRX is a C-language implementation of the GSM radio modem, +originally developed as the 'Transceiver' part of OpenBTS. This radio +modem offers an interface based on top of UDP streams. + +The OsmoBTS bts_model code for OsmoTRX is called +`osmo-bts-trx`. It implements the UDP stream interface of +OsmoTRX, so both parts can be used together to implement a complete GSM +BTS based on general-purpose computing SDR. + +As OsmoTRX is general-purpose software running on top of Linux, it is thus not +tied to any specific physical hardware. At the time of this writing, OsmoTRX +supports a variety of Lime Microsystems and Ettus USRP SDRs via the UHD driver, +as well as the Fairwaves UmTRX and derived products. + +OsmoTRX is not a complete GSM PHY but 'just' the radio modem. This +means that all of the Layer 1 functionality such as scheduling, +convolutional coding, etc. is actually also implemented inside OsmoBTS. + +As such, the boundary between OsmoTRX and `osmo-bts-trx` is at +a much lower interface, which is an internal interface of other more +traditional GSM PHY implementations. + +Besides OsmoTRX, there are also other implementations (both Free +Software and proprietary) that implement the same UDP stream based radio +modem interface. + + +=== `osmo-bts-trx` specific VTY commands + +For a auto-generated complete syntax reference of the VTY commands, +pleas see the associated _OsmoBTS VTY reference manual_ +<<vty-ref-osmobts>>. The section below only lists the most important +commands. + +==== at the 'SHOW' node + +===== `show transceivers` + +Display information about configured/connected OsmoTRX transceivers in +human-readable format to current VTY session. + +==== at the 'PHY' configuration node + +===== `osmotrx ip HOST` + +Set the IP address for the OsmoTRX interface for both the local (OsmoBTS) and +remote (OsmoTRX) side of the UDP flows. This option has been deprecated by the +more detailed option `osmotrx ip (local|remote) A.B.C.D`. + +===== `osmotrx ip (local|remote) A.B.C.D` + +Set the IP address for the OsmoTRX interface for either the local (OsmoBTS) or +remote (OsmoTRX) side of the UDP flows. + +===== `osmotrx base-port (local|remote) <0-65535>` + +Configure the base UDP port for the OsmoTRX interface for either the +local (OsmoBTS) or remote (OsmoTRX) side of the UDP flows. + +===== `osmotrx fn-advance <0-30>` + +Set the number of frames to be transmitted to transceiver in advance of +current GSM frame number. + +===== `osmotrx rts-advance <0-30>` + +Set the number of frames to be requested from PCU in advance of current +frame number. Do not change this unless you have a good reason! + +===== `osmotrx rx-gain <0-50>` + +Set the receiver gain (configured in the hardware) in dB. + +===== `osmotrx tx-attenuation <0-50>` + +Set the transmitter attenuation (configured in the hardware) in dB. + +===== `osmotrx tx-attenuation oml` + +Use the Value in the A-bis OML Attribute `MAX_POWER_REDUCTION` as +transmitter attenuation. + +==== at the 'PHY Instance' configuration node + +===== `slotmask (1|0) (1|0) (1|0) (1|0) (1|0) (1|0) (1|0) (1|0)` + +Configure which timeslots should be active on this TRX. Normally all +timeslots are enabled, unless you are running on a cpu-constrained +deeply embedded system. + +===== `osmotrx maxdly <0-31>` + +Set the maximum delay for received symbols (in number of GSM symbols). + + +== `osmo-bts-octphy` for Octasic OCTPHY-2G + +The Octasic OCTPHY-2G is a GSM PHY implementation inside an Octasic +proprietary 24-core DSP called OCTDSP. + +This DSP has a built-in Gigabit Ethernet interface, over which it +exchanges PHY-layer primitives in raw Ethernet frames with the upper +layers running on another CPU attached to the same Ethernet. Those +primitives are described in a set of C-language header files. + +OsmoBTS implements the raw Ethernet frame based primitives as well as +the associated transport protocol (OKTPKT/OCTVC1) in the +`osmo-btso-octphy` bts_model code. + +You can run the `osmo-bts-octphy` on any system connected to the same +Ethernet as the OCTDSP running the OCTPHY. This can be either an +embedded ARM or x86 SoM part of the OCTBTS hardware, or it can be any +other Linux system attached via an Ethernet switch. + +Each OCTDSP running OCTSDR-2G offers a set of primitives part of a +OCTPKT session, which is mapped to an OsmoBTS PHY link. Depending on +the OCTSDR-2G software version, you may create multiple software TRX by +creating multiple OsmoBTS PHY instances inside that PHY link. + +Multiple DSPs may exist in one circuit board, then each of the DSPs is +interfaced by one OsmoBTS PHY link, and each of them may have one or +more OsmoBTS PHY instances creating a Multi-TRX configuration. + + +== `osmo-bts-litecell15` for Nutaq/Nuran LiteCell 1.5 + +The Nutaq/Nuran LiteCell 1.5 implements a dual-transceiver GSM BTS based +on a mixed ARM/DSP/FPGA architecture. The PHY layer is implemented on +DSP/FPGA and similar to that of the sysmoBTS: It exchanges primitives +described in a set of C-language header files over message queues +between the ARM and the DSP. + +This interface is implemented in the `osmo-bts-litecell15` bts_model of +OsmoBTS. You would run `osmo-bts-litecell15` on the ARM/Linux processor +of the Litecell 1.5. + +The two transceivers of the Litecell 1.5 each have their own set of DSP +message queues. Each set of message queues is wrapped into one OsmoBTS +PHY link, offering one OsmoBTS PHY instance. + +The Litecell 1.5 PHY supports a direct PHY interface to OsmoPCU, +reducing the latency and amount of primitives that OsmoBTS would +otherwise need to pass through from the PHY message queues to the PCU +socket and vice-versa. + +=== `osmo-bts-trx` specific VTY commands + +For a auto-generated complete syntax reference of the VTY commands, +please see the associated _OsmoBTS VTY reference manual_ +<<vty-ref-osmobts>>. The section below only lists the most important +commands. + +==== at the 'SHOW' node + +===== `show phy <0-255> system-information` + +Show information about the hardware platform, DSP and OCTPHY-2G software +version. + +===== `show phy <0-255> rf-port-stats <0-1>` + +Show information about the RF port interfaces. + +===== `show phy <0-255> clk-sync-stats` + +Show information about the clock synchronization manager. + +==== at the 'PHY' configuration node + +===== `octphy hw-addr HWADDR` + +Specify the Ethernet hardware address (mac address) of the DSP running +the OCTPHY-2G software for this PHY link. + +===== `octphy net-device NAME` + +Specify the Ethernet network device (like `eth0`) through which the DSP +can be reached from OsmoBTS. + +===== `octphy rf-port-index <0-255>` + +Specify which RF port should be used for this PHY link. + +===== `octphy rx-gain <0-73>` + +Configure the receiver gain in dB. + +===== `octphy tx-attenuation <0-359>` + +Configure the transmitter attenuation in quarter-dB + + + + +== `osmo-bts-virtual` for Virtual Um Interface + +This is a special BTS model used for research, simulation and testing. +Rather than communicating over a wireless RF interface, the GSM Um +messages are encapsulated over GSMTAP/UDP/IP. + +The Virtual Um interface (i.e. virtual radio layer) between OsmoBTS and +OsmocomBB allows us to run a complete GSM network with 1-N BTSs and 1-M +MSs without any actual radio hardware, which is of course excellent for +all kinds of testing scenarios. + +The Virtual Um layer is based on sending L2 frames (blocks) encapsulated +via GSMTAP UDP multicast packets. There are two separate multicast +groups, one for uplink and one for downlink. The multicast nature +simulates the shared medium and enables any simulated phone to receive +the signal from multiple BTSs via the downlink multicast group. + +In OsmoBTS, this is implemented via the `osmo-bts-virtual` BTS model. + +Setting up OsmoBTS in its `osmo-bts-virtual` flavor isn't really much +different from setting it up with real hardware. The amount of required +configuration at the BTS configuration file is (as always) very minimal, +as in the GSM network architecture provides almost all relevant +configuration to the BTS from the BSC. + +An example configuratin file is provided as part of the osmo-bts source +code: `doc/examples/virtual/osmobts-virtual.cfg` + +For more information see +http://osmocom.org/projects/cellular-infrastructure/wiki/Virtual_Um + +=== `osmo-bts-virtual` specific VTY commands + +For a auto-generated complete syntax reference of the VTY commands, +please see the associated _OsmoBTS VTY reference manual_ +<<vty-ref-osmobts>>. The section below only lists the most important +commands. + +==== at the 'PHY' config node + +===== `virtual-um net-device NETDEV` + +Configure the network device used for sending/receiving the virtual Um +interface messages (e.g. `eth0`). + +===== `virtual-um ms-udp-port <0-65535>` + +Configure the UDP port used for sending virtual Um +downlink messages towards the MS (default: GSMTAP 4729). + +===== `virtual-um ms-multicast-group GROUP` + +Configure the IP multicast group used for sending virtual +Um downlink messages towards the MS (default: 239.193.23.1) + +===== `virtual-um bts-udp-port <0-65535>` + +Configure the UDP port used for receiving virtual Um +uplink messages from the MS (default: GSMTAP 4729). + +===== `virtual-um bts-multicast-group GROUP` + +Configure the IP multicast group used for receiving virtual +Um uplink messages from the MS (default: 239.193.23.2) diff --git a/doc/manuals/chapters/configuration.adoc b/doc/manuals/chapters/configuration.adoc new file mode 100644 index 00000000..558bd4ba --- /dev/null +++ b/doc/manuals/chapters/configuration.adoc @@ -0,0 +1,210 @@ +== 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 + +Ths 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'] [-r 'PRIO'] [-i 'GSMTAP-IP'] [-t <1-255>] + +==== 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. +*-r, --realtime 'PRIO'*:: + Enable use of the Linux kernel realtime priority scheduler with + the specified priority. + It is recommended you use this option on low-performance + embedded systems or systems that encounter high non-GSM/GPRS + load. +*-i, --gsmtap-ip 'GSMTAP-IP'*:: + Specify the destination IP address for GSMTAP messages. +*-t, --trx-num <1-255>*:: + Specify the number of TRX supported by this BTS. + +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 start +OsmoBTS using the `-i` or `--gsmtap-ip` command line option, specifying +the destination IP address for the GSMTAP messages. In most cases, +using 127.0.0.1 for passing the messages over the loopback (`lo`) device +will be sufficient. + +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)# trx 0 +OsmoBTS(trx)# 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 `trx` node of the OsmoBTS VTY. + +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) at the IP address specified in the command line +argument. + +==== Configuring power ramping + +OsmoBTS can ramp up the power of its trx over time. This helps reduce +cell congestion in busy environments. + +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 +---- diff --git a/doc/manuals/chapters/control.adoc b/doc/manuals/chapters/control.adoc new file mode 100644 index 00000000..3b21669b --- /dev/null +++ b/doc/manuals/chapters/control.adoc @@ -0,0 +1,24 @@ +[[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 OsmoBTS. The commands starting with prefix +"net.btsN." are specific to a certain BTS so N have to be replaced with BTS +number when issuing command. Similarly the +TRX-specific commands are additionally prefixed with TRX number e. g. +"net.bts1.trx2.thermal-attenuation". + + +.Variables available over control interface +[options="header",width="100%",cols="20%,5%,5%,50%,20%"] +|=== +|Name|Access|Trap|Value|Comment +|net.btsN.trxM.thermal-attenuation|RW|No|integer|See <<ther>> for details. +|=== + +[[ther]] +=== thermal-attenuation + +Allowed SET value for thermal attenuation is between 0 to 40 dB. Note: the value +is SET in dB units but GET will return value in mdB units used internally. diff --git a/doc/manuals/chapters/dynamic-timeslots.adoc b/doc/manuals/chapters/dynamic-timeslots.adoc new file mode 100644 index 00000000..7c43d187 --- /dev/null +++ b/doc/manuals/chapters/dynamic-timeslots.adoc @@ -0,0 +1,20 @@ +== Support for Dynamic Timeslots (TCH/F, TCH/H, PDCH) + +OsmoBTS supports dynamic switchover of timeslots between different physical +channel configurations, initiated by the BSC via (non-standard) Abis messages +-- see the _OsmoBTS Abis Protocol Specification_ <<osmobts-abis-spec>>. + +The Abis message handling for dynamic timeslots is independent of the BTS +model. However, dynamic switchover will only work for BTS models that implement +the internal API to reconnect a timeslot (_bts_model_ts_disconnect()_ and +_bts_model_ts_connect()_, see also <<osmobts_hardware_support>>). + +Currently, these OsmoBTS models support dynamic timeslots: + +* _osmo-bts-sysmo_ +* _osmo-bts-litecell15_ +* _osmo-bts-trx_ + +Dynamic timeslots are driven by the BSC and need to be configured there. When +using OsmoBSC or OsmoNITB, see the BTS configuration chapter on dynamic +timeslots in <<userman-osmobsc>> or <<userman-osmonitb>>, respectively. diff --git a/doc/manuals/chapters/interfaces.adoc b/doc/manuals/chapters/interfaces.adoc new file mode 100644 index 00000000..9fefa729 --- /dev/null +++ b/doc/manuals/chapters/interfaces.adoc @@ -0,0 +1,156 @@ +== OsmoBTS Interfaces + +OsmoBTS offers a set of interfaces to interact with external entities: + +* A-bis/IP interface to talk to the BSC +* bts_model specific PHY interface +* VTY interface +* Osmocom control interface +* GSMTAP interface +* PCU interface + + +=== OsmoBTS Abis/IP Interface + +OsmoBTS implements the GSM A-bis interface as described in the relevant +3GPP specifications: + +* A-bis RSL according to 3GPP TS 08.58 +* A-bis OML according to 3GPP TS 12.21 + +As the 3GPP specifies A-bis only over E1 interfaces and not over IP, +significant enhancements and modifications to the 3GPP specifications are +employed. Nevertheless, the implementation tries to stay as close as +possible to the 3GPP specifications. + +Please see the _OsmoBTS Abis Protocol Specification_ +<<osmobts-abis-spec>> for more information on this subject. + + +=== bts_model specific PHY interface + +This interface is specific to the bts_model that OsmoBTS was compiled +for. It can take any form as required by the respective hardware. + +Please see the PHY documentation of your respective BTS hardware for more +details. + + +=== OsmoBTS VTY Interface + +See <<vty>> for further information. + + +=== OsmoBTS Control Interface + +The general structure of the Omsocom control interface is described in +<<common-control-if>>. + +The number of control interface commands/attributes is currently quite +limited and largely depends on the bts_model used. + +==== trx.N.thermal-attenuation + +The idea of this parameter is to attenuate the system output power as part of +thermal management. In some cases the PA might be passing a critical level, +so an external control process can use this attribute to reduce the system +output power. + +Please note that all values in the context of transmit power calculation +are integers in milli-dB (1/10000 bel), so the below example is setting +the attenuation at 3 dB: + +---- +bsc_control.py -d localhost -p 4238 -s trx.0.thermal-attenuation 3000 +Got message: SET_REPLY 1 trx.0.thermal-attenuation 3000 +---- + +---- +bsc_control.py -d localhost -p 4238 -g trx.0.thermal-attenuation +Got message: GET_REPLY 1 trx.0.thermal-attenuation 3000 +---- + + + +=== OsmoBTS GSMTAP Interface + +GSMTAP is a standard created by Osmocom to UDP-encapsulate GSM protocol +messages normally communicated over non-IP interfaces for the primary +purpose of protocol analysis in the wireshark dissector. + +The initial purpose was to encapsulate GSM Um frames including some +meta-data like ARFCN and GSM frame number into something that can be +parsed and dispatched within the wireshark dissector. + +This interface has since been extended to many other +GSM/GPRS/UMTS interfaces and protocols, and even to TETRA and GMR. + +In OsmoBTS, it is possible to export both uplink and downlink Um +messages via GSMTAP. There is a set of VTY configuration options to +specify for which logical channels of the Um interface GSMTAP messages +shall be emitted, and to which destination IP address they shall be +sent. + +Using GSMTAP it is possible to place a virtual tap at the air interface +between BTS and MS, without going through the trouble of setting up an +actual radio receiver at the same frequencies. Also, GSMTAP export is +performed before the Um air-interface encryption (A5) is performed, so +all frames are always in plain text. + +Please refer to <<gsmtap>> for more information on how to configure and +use this interface. + + +=== OsmoBTS PCU Socket Interface + +In order to assist the provisioning of GPRS services over the same radio +interface as circuit-switched GSM, OsmoBTS exposes a Unix domain socket +based interface towards OsmoPCU. + +OsmoPCU is the Osmocom implementation of the GPRS Packet Control Unit +(PCU), which is co-located with the BTS in the Osmocom implementation. +Contrary to that, many classic E1-based implementations of the GSM RAN +co-locate the PCU with the BSC. However, the GSM specifications keep +the location up to the implementor. + +The GPRS network architecture is shown in <<fig-gprs-pcubts>>. + +[[fig-gprs-pcubts]] +.GPRS network architecture +[graphviz] +---- +digraph G { + rankdir=LR; + MS0 [label="MS"]; + MS1 [label="MS"]; + BTS; + BSC; + MSC; + PCU; + SGSN; + GGSN; + MS0->BTS [label="Um"]; + MS1->BTS [label="Um"]; + BTS->BSC [label="Abis"]; + BSC->MSC [label="A"]; + BTS->PCU [label="pcu_sock"]; + PCU->SGSN [label="Gb"]; + SGSN->GGSN [label="GTP"]; +} +---- + +The PCU socket interface serves the following purposes: + +* to pass PCU relevant configuration from BTS to PCU +* to forward paging requests from BTS to PCU +* to forward RACH Requests from BTS to PCU + +Depending on your bts_model, the PCU may also be passing actual +PH-DATA.request / PH-DATA.indication / PH-RTS.indication primitives for +the PDCH. This is considered sub-optimal, and some BTS models offer a +direct interface by which the PCU can exchange those primitives directly +with the PHY. + +The default PCU socket interface name is `/tmp/pcu_sock`, but this can +be overridden by the `pcu-socket` VTY command in the BTS configuration +VTY node. diff --git a/doc/manuals/chapters/overview.adoc b/doc/manuals/chapters/overview.adoc new file mode 100644 index 00000000..6b6b8284 --- /dev/null +++ b/doc/manuals/chapters/overview.adoc @@ -0,0 +1,105 @@ +== Overview + +=== About this manual + +This manual should help you getting started with the OsmoBTS software. +It will cover aspects of configuring and running OsmoBTS as well as some +introduction about its internal architecture and external interfaces. + +=== About OsmoBTS + +OsmoBTS is an implementation of a GSM BTS (Base Transceiver Station). A +BTS serves as the interface between the Um radio interface towards +phones and the wired Abis interface towards the BSC (Base Station +Controller). It also implements the network side of the Layer 2 of the +Um radio interface: The LAPDm protocol. + +OsmoBTS is licensed as Free and Open Source Software (FOSS) under _GNU +AGPLv3_ <<gnu-agplv3>>. It is developed as one GSM network +infrastructure component part of the overall Osmocom project. + +As perhaps the first implementation of a GSM BTS ever in the industry, +OsmoBTS is implemented in a vendor-independent way and supports a large +variety of transceiver hardware and physical layer implementations from +many vendors. + +=== Credits + +OsmoBTS was originally developed in 2011 by Andreas Eversberg and Harald +Welte. It has since been maintained by Harald Welte and Holger Freyther +at sysmocom. + +=== OsmoBTS in the Osmocom GSM network architecture + +OsmoBTS can be used in combination with the various other GSM network +elements developed under the umbrella of the Osmocom project. + +Typical configurations either use OsmoBTS with OsmoBSC, or with +OsmoNITB, as can be seen in the following figures. + +[[fig-gsm-classic]] +.Classic GSM archtiecture using OsmoBTS with OsmoBTS components +[graphviz] +---- +digraph G { + rankdir=LR; + MS0 [label="MS"] + MS1 [label="MS"] + MS2 [label="MS"] + MS3 [label="MS"] + BTS0 [label="OsmoBTS"] + BTS1 [label="OsmoBTS"] + BSC [label="OsmoBSC"] + MSC [label="MSC/VLR"] + HLR [label="HLR/AUC"] + MS0->BTS0 [label="Um"] + MS1->BTS0 [label="Um"] + MS2->BTS1 [label="Um"] + MS3->BTS1 [label="Um"] + BTS0->BSC [label="Abis"] + BTS1->BSC [label="Abis"] + BSC->MSC [label="A"] + MSC->HLR [label="C"] + MSC->EIR [label="F"] + MSC->SMSC +} +---- + + +[[fig-gsm-nitb]] +.GSM architecture using OsmoBTS + OsmoNITB +[graphviz] +---- +digraph G { + rankdir=LR; + MS0 [label="MS"] + MS1 [label="MS"] + MS2 [label="MS"] + MS3 [label="MS"] + BTS0 [label="OsmoBTS"] + BTS1 [label="OsmoBTS"] + MS0->BTS0 [label="Um"] + MS1->BTS0 [label="Um"] + MS2->BTS1 [label="Um"] + MS3->BTS1 [label="Um"] + BTS0->BSC [label="Abis"] + BTS1->BSC [label="Abis"] + subgraph cluster_nitb { + label = "OsmoNITB"; + BSC + MSC [label="MSC/VLR"] + HLR [label="HLR/AUC"] + BSC->MSC [label="A"] + MSC->HLR [label="C"] + MSC->EIR [label="F"] + MSC->SMSC; + } +} +---- + +If intended by the user, it is of course also possible to implement an +OsmoBTS-compatible Abis-over-IP interface in any third party BSC. The +Abis/IP interface and its protocol are documented in the _OsmoBTS +Abis Protocol Specification_ <<osmobts-abis-spec>>. However, be advised +that such a configuration is currently not officially supported by +Osmocom. |