Introduce OsmoTRX manual
Change-Id: I19ee9d6cda02fb7200c96c0ac129e69825b096cd
This commit is contained in:
parent
c6541e6c26
commit
8072650406
|
@ -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
|
|
@ -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).
|
|
@ -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
|
||||
|===
|
|
@ -0,0 +1,4 @@
|
|||
[[counters]]
|
||||
== Counters
|
||||
|
||||
include::./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
|
|
@ -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];
|
||||
}
|
||||
----
|
|
@ -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.
|
|
@ -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>
|
|
@ -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[]
|
|
@ -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>
|
|
@ -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
Loading…
Reference in New Issue