Introduce OsmoTRX manual

Change-Id: I19ee9d6cda02fb7200c96c0ac129e69825b096cd
This commit is contained in:
Pau Espin 2018-03-06 16:15:24 +01:00 committed by Neels Hofmeyr
parent c6541e6c26
commit 8072650406
12 changed files with 1447 additions and 0 deletions

10
doc/manuals/Makefile Normal file
View File

@ -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

View File

@ -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).

View File

@ -0,0 +1,12 @@
[[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 OsmoTRX.
.Variables available over control interface
[options="header",width="100%",cols="20%,5%,5%,50%,20%"]
|===
|Name|Access|Trap|Value|Comment
|===

View File

@ -0,0 +1,4 @@
[[counters]]
== Counters
include::./counters_generated.adoc[]

View File

@ -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

View File

@ -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];
}
----

View File

@ -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.

View File

@ -0,0 +1,46 @@
<revhistory>
<revision>
<revnumber>1</revnumber>
<date>March 6, 2019</date>
<authorinitials>PE</authorinitials>
<revremark>
Initial version.
</revremark>
</revision>
</revhistory>
<authorgroup>
<author>
<firstname>Pau</firstname>
<surname>Espin Pedrol</surname>
<email>pespin@sysmocom.de</email>
<authorinitials>PE</authorinitials>
<affiliation>
<shortaffil>sysmocom</shortaffil>
<orgname>sysmocom - s.f.m.c. GmbH</orgname>
<jobtitle>Software Developer</jobtitle>
</affiliation>
</author>
</authorgroup>
<copyright>
<year>2018</year>
<holder>sysmocom - s.f.m.c. GmbH</holder>
</copyright>
<legalnotice>
<para>
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".
</para>
<para>
The Asciidoc source code of this manual can be found at
<ulink url="http://git.osmocom.org/osmo-gsm-manuals/">
http://git.osmocom.org/osmo-gsm-manuals/
</ulink>
</para>
</legalnotice>

View File

@ -0,0 +1,32 @@
:gfdl-enabled:
OsmoTRX User Manual
====================
Pau Espin Pedrol <pespin@sysmocom.de>
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[]

View File

@ -0,0 +1,37 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
ex:ts=2:sw=42sts=2:et
-*- tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*-
-->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V5.0//EN"
"http://www.docbook.org/xml/5.0/dtd/docbook.dtd" [
<!ENTITY chapter-vty SYSTEM "../common/chapters/vty.xml" >
<!ENTITY sections-vty SYSTEM "generated/docbook_vty.xml" >
]>
<book>
<info>
<revhistory>
<revision>
<revnumber>v1</revnumber>
<date>6th March 2018</date>
<authorinitials>pe</authorinitials>
<revremark>Initial</revremark>
</revision>
</revhistory>
<title>OsmoTRX VTY Reference</title>
<copyright>
<year>2018</year>
</copyright>
<legalnotice>
<para>This work is copyright by <orgname>sysmocom - s.f.m.c. GmbH</orgname>. All rights reserved.
</para>
</legalnotice>
</info>
<!-- Main chapters-->
&chapter-vty;
</book>

View File

@ -0,0 +1,2 @@
<vtydoc xmlns='urn:osmocom:xml:libosmocore:vty:doc:1.0'>
</vtydoc>

File diff suppressed because it is too large Load Diff