From fe5b55e1c80432a0a50bdd21b605b93a704605bf Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Tue, 6 Mar 2018 16:15:24 +0100 Subject: Introduce OsmoTRX manual Change-Id: I19ee9d6cda02fb7200c96c0ac129e69825b096cd --- Makefile | 4 + OsmoTRX/Makefile | 10 + OsmoTRX/chapters/configuration.adoc | 36 + OsmoTRX/chapters/control.adoc | 12 + OsmoTRX/chapters/counters.adoc | 4 + OsmoTRX/chapters/counters_generated.adoc | 7 + OsmoTRX/chapters/overview.adoc | 59 ++ OsmoTRX/chapters/running.adoc | 19 + OsmoTRX/osmotrx-usermanual-docinfo.xml | 46 ++ OsmoTRX/osmotrx-usermanual.adoc | 32 + OsmoTRX/osmotrx-vty-reference.xml | 37 + OsmoTRX/vty/trx_vty_additions.xml | 2 + OsmoTRX/vty/trx_vty_reference.xml | 1183 ++++++++++++++++++++++++++++++ 13 files changed, 1451 insertions(+) create mode 100644 OsmoTRX/Makefile create mode 100644 OsmoTRX/chapters/configuration.adoc create mode 100644 OsmoTRX/chapters/control.adoc create mode 100644 OsmoTRX/chapters/counters.adoc create mode 100644 OsmoTRX/chapters/counters_generated.adoc create mode 100644 OsmoTRX/chapters/overview.adoc create mode 100644 OsmoTRX/chapters/running.adoc create mode 100644 OsmoTRX/osmotrx-usermanual-docinfo.xml create mode 100644 OsmoTRX/osmotrx-usermanual.adoc create mode 100644 OsmoTRX/osmotrx-vty-reference.xml create mode 100644 OsmoTRX/vty/trx_vty_additions.xml create mode 100644 OsmoTRX/vty/trx_vty_reference.xml diff --git a/Makefile b/Makefile index 45fe129..4e821f5 100644 --- a/Makefile +++ b/Makefile @@ -15,6 +15,7 @@ all: check-deps cd OsmoSTP; $(MAKE) cd OsmocomBB; $(MAKE) cd OsmoMGW; $(MAKE) + cd OsmoTRX; $(MAKE) clean: cd OsmoBTS; $(MAKE) clean @@ -31,6 +32,7 @@ clean: cd OsmoSTP; $(MAKE) clean cd OsmocomBB; $(MAKE) clean cd OsmoMGW; $(MAKE) clean + cd OsmoTRX; $(MAKE) clean upload: cd OsmoBTS; $(MAKE) upload @@ -47,6 +49,7 @@ upload: cd OsmoSTP; $(MAKE) upload cd OsmocomBB; $(MAKE) upload cd OsmoMGW; $(MAKE) upload + cd OsmoTRX; $(MAKE) upload check: cd OsmoBTS; $(MAKE) check @@ -65,6 +68,7 @@ check: cd OsmoHLR; $(MAKE) check cd OsmoSTP; $(MAKE) check cd OsmocomBB; $(MAKE) check + cd OsmoTRX; $(MAKE) check define check_dep_bin @type $(1) >/dev/null 2>&1 || { echo >&2 "Binary '$(1)' not found in path, please install $(2)."; exit 1; } diff --git a/OsmoTRX/Makefile b/OsmoTRX/Makefile new file mode 100644 index 0000000..81aec9a --- /dev/null +++ b/OsmoTRX/Makefile @@ -0,0 +1,10 @@ +TOPDIR = .. + +ASCIIDOC = osmotrx-usermanual.adoc +ASCIIDOC_DEPS = chapters/*.adoc +include $(TOPDIR)/build/Makefile.asciidoc.inc + +VTY_REFERENCE = osmotrx-vty-reference.xml +include $(TOPDIR)/build/Makefile.vty-reference.inc + +include $(TOPDIR)/build/Makefile.common.inc diff --git a/OsmoTRX/chapters/configuration.adoc b/OsmoTRX/chapters/configuration.adoc new file mode 100644 index 0000000..cdde366 --- /dev/null +++ b/OsmoTRX/chapters/configuration.adoc @@ -0,0 +1,36 @@ +== Configuring OsmTRX + +OsmoTRX will read the configuration at startup time and configure the +transceiver accordingly after validating the configuration. + +OsmoTRX can handle several TRX channels, but at least one must be configured in +order to be able to start it successfully. Channels must be present in the +configuration file in incremental order, starting from 0 and be consecutive. + +Example configuration files for different devices and setups can be found in +`doc/examples/` in 'osmo-trx' git repository. + +=== Documented example + +.Example: Static GGSN/APN configuration (single catch-all GGSN) +---- +trx + bind-ip 127.0.0.1 <1> + remote-ip 127.0.0.1 <2> + base-port 5700 <3> + egprs disable <4> + tx-sps 4 <5> + rx-sps 4 <6> + chan 0 <7> + tx-path BAND1 <8> + rx-path LNAW <9> +---- +<1> Configure the local IP address at the TRX used for the connection against `osmo-bts-trx`. +<2> Specify the IP address of `osmo-bts-trx` to connect to. +<3> Specify the reference base UDP port to use for communication. +<4> Don't enable EDGE support. +<5> Use 4 TX samples per symbol. This is device specific. +<6> Use 4 RX samples per symbol. This is device specific. +<7> Configure the first channel. As no other channels are specified, `osmo-trx` assumes it is using only one channel. +<8> Configure the device to use `BAND1` Tx antenna path from all the available ones (device specific). +<9> Configure the device to use `LNAW` Rx antenna path from all the available ones (device specific). diff --git a/OsmoTRX/chapters/control.adoc b/OsmoTRX/chapters/control.adoc new file mode 100644 index 0000000..168769a --- /dev/null +++ b/OsmoTRX/chapters/control.adoc @@ -0,0 +1,12 @@ +[[control]] +== Control interface + +The actual protocol is described in <>, the variables +common to all programs using it are described in <>. Here we +describe variables specific to OsmoTRX. + +.Variables available over control interface +[options="header",width="100%",cols="20%,5%,5%,50%,20%"] +|=== +|Name|Access|Trap|Value|Comment +|=== diff --git a/OsmoTRX/chapters/counters.adoc b/OsmoTRX/chapters/counters.adoc new file mode 100644 index 0000000..7fbb10c --- /dev/null +++ b/OsmoTRX/chapters/counters.adoc @@ -0,0 +1,4 @@ +[[counters]] +== Counters + +include::./counters_generated.adoc[] diff --git a/OsmoTRX/chapters/counters_generated.adoc b/OsmoTRX/chapters/counters_generated.adoc new file mode 100644 index 0000000..b40dc37 --- /dev/null +++ b/OsmoTRX/chapters/counters_generated.adoc @@ -0,0 +1,7 @@ +// autogenerated by show asciidoc counters +These counters and their description based on OsmoTRX 0.2.0.61-408f (OsmoTRX). + +// generating tables for rate_ctr_group +// generating tables for osmo_stat_items +// generating tables for osmo_counters +// there are no ungrouped osmo_counters diff --git a/OsmoTRX/chapters/overview.adoc b/OsmoTRX/chapters/overview.adoc new file mode 100644 index 0000000..b7d9697 --- /dev/null +++ b/OsmoTRX/chapters/overview.adoc @@ -0,0 +1,59 @@ +[[chapter_introduction]] +== Overview + +[[intro_overview]] +=== About OsmoTRX + +OsmoTRX is a C/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. +OsmoTRX is a software-defined radio transceiver that implements the Layer 1 +physical layer of a BTS comprising the following 3GPP specifications: + +* TS 05.01 "Physical layer on the radio path" +* TS 05.02 "Multiplexing and Multiple Access on the Radio Path" +* TS 05.04 "Modulation" +* TS 05.10 "Radio subsystem synchronization + +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. + +[[fig-gprs-pcubts]] +.GSM network architecture with OsmoTRX and OsmoBTS +[graphviz] +---- +digraph G { + rankdir=LR; + MS0 [label="MS"]; + MS1 [label="MS"]; + MS0->SDR[label="Um"]; + MS1->SDR [label="Um"]; + SDR -> OsmoTRX [label="Raw Samples"]; + OsmoTRX->BTS [label="bursts over UDP"]; + BTS->BSC [label="Abis"]; + BSC->MSC [label="A"]; + BTS->PCU [label="pcu_sock"]; + PCU->SGSN [label="Gb"]; + OsmoTRX [color=red]; +} +---- diff --git a/OsmoTRX/chapters/running.adoc b/OsmoTRX/chapters/running.adoc new file mode 100644 index 0000000..7ed2884 --- /dev/null +++ b/OsmoTRX/chapters/running.adoc @@ -0,0 +1,19 @@ +== Running OsmoTRX + +The OsmoTRX executable (`osmo-trx`) offers the following command-line +options: + + +=== SYNOPSIS + +*osmo-trx* [-h] [-C 'CONFIGFILE'] + + +=== OPTIONS + +*-h*:: + Print a short help message about the supported options +*-C 'CONFIGFILE'*:: + Specify the file and path name of the configuration file to be + used. If none is specified, use `osmo_trx.cfg` in the current + working directory. diff --git a/OsmoTRX/osmotrx-usermanual-docinfo.xml b/OsmoTRX/osmotrx-usermanual-docinfo.xml new file mode 100644 index 0000000..34225be --- /dev/null +++ b/OsmoTRX/osmotrx-usermanual-docinfo.xml @@ -0,0 +1,46 @@ + + + 1 + March 6, 2019 + PE + + Initial version. + + + + + + + Pau + Espin Pedrol + pespin@sysmocom.de + PE + + sysmocom + sysmocom - s.f.m.c. GmbH + Software Developer + + + + + + 2018 + sysmocom - s.f.m.c. GmbH + + + + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with no Invariant Sections, no Front-Cover Texts, + and no Back-Cover Texts. A copy of the license is included in + the section entitled "GNU Free Documentation License". + + + The Asciidoc source code of this manual can be found at + + http://git.osmocom.org/osmo-gsm-manuals/ + + + diff --git a/OsmoTRX/osmotrx-usermanual.adoc b/OsmoTRX/osmotrx-usermanual.adoc new file mode 100644 index 0000000..249a21c --- /dev/null +++ b/OsmoTRX/osmotrx-usermanual.adoc @@ -0,0 +1,32 @@ +:gfdl-enabled: + +OsmoTRX User Manual +==================== +Pau Espin Pedrol + + +include::../common/chapters/preface.adoc[] + +include::chapters/overview.adoc[] + +include::chapters/running.adoc[] + +include::../common/chapters/control_if.adoc[] + +include::chapters/control.adoc[] + +include::../common/chapters/vty.adoc[] + +include::../common/chapters/logging.adoc[] + +include::chapters/counters.adoc[] + +include::chapters/configuration.adoc[] + +include::../common/chapters/port_numbers.adoc[] + +include::../common/chapters/bibliography.adoc[] + +include::../common/chapters/glossary.adoc[] + +include::../common/chapters/gfdl.adoc[] diff --git a/OsmoTRX/osmotrx-vty-reference.xml b/OsmoTRX/osmotrx-vty-reference.xml new file mode 100644 index 0000000..653f5b1 --- /dev/null +++ b/OsmoTRX/osmotrx-vty-reference.xml @@ -0,0 +1,37 @@ + + + + +]> + + + + + + v1 + 6th March 2018 + pe + Initial + + + + OsmoTRX VTY Reference + + + 2018 + + + + This work is copyright by sysmocom - s.f.m.c. GmbH. All rights reserved. + + + + + + &chapter-vty; + diff --git a/OsmoTRX/vty/trx_vty_additions.xml b/OsmoTRX/vty/trx_vty_additions.xml new file mode 100644 index 0000000..a4c675e --- /dev/null +++ b/OsmoTRX/vty/trx_vty_additions.xml @@ -0,0 +1,2 @@ + + diff --git a/OsmoTRX/vty/trx_vty_reference.xml b/OsmoTRX/vty/trx_vty_reference.xml new file mode 100644 index 0000000..ffc642a --- /dev/null +++ b/OsmoTRX/vty/trx_vty_reference.xml @@ -0,0 +1,1183 @@ + + + Common Commands + These commands are available on all VTY nodes. They are listed here only once, to unclutter the VTY reference. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + view + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + enable + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + config + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + config-log + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + config-stats + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + config-line + + + + + + + + + + + + + + + + + + + + config-ctrl + + + + + + + + + config-trx + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + config-trx-chan + + + + + + + + + + + + + + -- cgit v1.2.3