doc/manual: Refactor, rewrite, improve and update most of the User Manual
* Some TODOs are added as comments which actually require code changes.
These are details which showed up as incongruences or missing bits
while writing the documentation for them.
* Some sections are introduced but still waiting to be writen soon:
** Debugging section
** Docker Setup section
** Ansible Setup section
** Troubleshooting (add jenkins red cross button sending kill -9)
** resources.conf attribute list needs to be converted to a table
* Device related setup needs to be updated and extended
* Parametrized scenarios need to be documented
* 4G resources documentation needs to be added.
Change-Id: Ifc2a3c74d45336cc988b76c0ff68a85311e4dd40
diff --git a/doc/manuals/chapters/intro.adoc b/doc/manuals/chapters/intro.adoc
index 14daba4..9b7131d 100644
--- a/doc/manuals/chapters/intro.adoc
+++ b/doc/manuals/chapters/intro.adoc
@@ -1,31 +1,56 @@
-== Introduction with Examples
+== Introduction
-The osmo-gsm-tester is software to run automated tests of real GSM hardware,
+{app-name} is a software to run automated tests on real GSM hardware,
foremost to verify that ongoing Osmocom software development continues to work
-with various BTS models, while being flexibly configurable and extendable.
+with various BTS models, while being flexibly configurable and extendable to
+work for other technologies, setups and projects. It can be used for instance to
+test a 3G or 4G network.
-A 'main unit' (general purpose computer) is connected via ethernet and/or USB to
-any number of BTS models and to any number of GSM modems via USB. The modems
-and BTS instances' RF transceivers are typically wired directly to each other
-via RF distribution chambers to bypass the air medium and avoid disturbing real
-production cellular networks. Furthermore, the setup may include adjustable RF
-attenuators to model various distances between modems and base stations.
+{app-name} (python3 process) runs on a host (general purpose computer) named
+the 'main unit'. It may optionally be connected to any number of 'slave units',
+which {app-name} may use to orchestrate processes remotely, usually through SSH.
-The osmo-gsm-tester software runs on the main unit to orchestrate the various
-GSM hardware and run predefined test scripts. It typically receives binary
-packages from a jenkins build service. It then automatically configures and
-launches an Osmocom core network on the main unit and sets up and runs BTS
-models as well as modems to form a complete ad-hoc GSM network. On this setup,
-predefined test suites, combined with various scenario definitions, are run to
-verify stability of the system.
+Hardware devices such as BTS, SDRs, modems, smart plugs, etc. are then connected
+to either the main unit or slaves units via IP, raw ethernet, USB or any other
+means·
-The osmo-gsm-tester is implemented in Python (version 3). It uses the ofono
-daemon to control the modems connected via USB. BTS software is either run
-directly on the main unit (e.g. for osmo-bts-trx, osmo-bts-octphy), run via SSH
-(e.g. for a sysmoBTS) or assumed to run on a connected BTS model (e.g. for
-ip.access nanoBTS).
+The modems and BTS instances' RF transceivers are typically wired directly to
+each other via RF distribution chambers to bypass the air medium and avoid
+disturbing real production cellular networks. Furthermore, the setup may include
+adjustable RF attenuators to model various distances between modems and base
+stations.
-.Typical osmo-gsm-tester setup
+Each of these devices, having each a different physical setup and configuration,
+supported features, attributes, etc., is referred in {app-name} terminology as a
+_resource_. Each _resource_ is an instance of _resource class_. A
+_resource_class_ may be for instance a _modem_ or a _bts_. For instance, an
+{app-name} setup may have 2 _modem_ instances and 1 _bts_ instances. Each of
+these _resources_ are listed and described in configuration files passed to
+{app-name}, which maintains a pool of _resources_ (available, in use, etc.).
+
+{app-name} typically receives from a jenkins build service the software or
+firmware binary packages to be used and tested. {app-name} then launches a
+specific set of testsuites which, in turn, contain each a set of python test
+scripts. Each test uses the _testenv_ API provided by {app-name} to configure,
+launch and manage the different nodes and processes from the provided binary
+packages to form a complete ad-hoc GSM network.
+
+Testsuites themselves contain configuration files to list how many resources it
+requires to run its tests. It also provides means to _filter_ which kind of
+_resources_ will be needed based on their attributes. This allows, for instance,
+asking {app-name} to provide a _modem_ supporting GPRS, or to provide a specific
+model of _bts_ such as a nanoBTS. Testsuites also allow receiving _modifiers_,
+which overwrite some of the default values that {app-name} itself or different
+_resources_ use.
+
+Moreover, one may want to run the same testsuite several tiems, each with
+different set of _resources_. For instance, one may want to run a testsuite with
+a sysmoBTS and later with a nanoBTS. This is supported by leaving the testsuite
+configuration generic enough and then passing _scenarios_ to it, which allow
+applying extra _filters_ or _modifiers_. Scenarios can also be combined to
+filter further or to apply further modifications.
+
+.Sample osmo-gsm-tester node 2G setup
[graphviz]
----
digraph G {
@@ -35,8 +60,8 @@
label = "GSM Hardware";
style=dotted
- modem0 [shape=box label="Modems..."]
- modem1 [shape=box label="Modems..."]
+ modem0 [shape=box label="Modem (Quectel EC20)"]
+ modem1 [shape=box label="Modems (SierraWireless MC7455)"]
osmo_bts_sysmo [label="sysmocom sysmoBTS\nrunning osmo-bts-sysmo" shape=box]
B200 [label="Ettus B200" shape=box]
sysmoCell5K [label="sysmocom sysmoCell5000" shape=box]
@@ -46,13 +71,16 @@
{modem0 modem1 osmo_bts_sysmo B200 octphy nanoBTS sysmoCell5K}->rf_distribution [dir=both arrowhead="curve" arrowtail="curve"]
}
+ subgraph cluster_slave_unit {
+ label = "Slave Unit"
+ osmo_trx [label="osmo-trx"]
+ }
subgraph cluster_main_unit {
label = "Main Unit"
osmo_gsm_tester [label="Osmo-GSM-Tester\ntest suites\n& scenarios"]
subgraph {
rank=same
ofono [label="ofono daemon"]
- osmo_trx [label="osmo-trx"]
osmo_bts_trx [label="osmo-bts-trx"]
osmo_bts_octphy [label="osmo-bts-octphy"]
OsmoNITB [label="BSC + Core Network\n(Osmo{NITB,MSC,BSC,HLR,...})"]
@@ -62,339 +90,15 @@
jenkins->osmo_gsm_tester [label="trial\n(binaries)"]
osmo_gsm_tester->jenkins [label="results"]
- ofono->{modem0 modem1} [label="USB"]
+ ofono->{modem0 modem1} [label="QMI/USB"]
osmo_gsm_tester->{OsmoNITB osmo_bts_trx osmo_bts_octphy}
- osmo_gsm_tester->osmo_bts_sysmo [taillabel="SSH"]
+ osmo_gsm_tester->{osmo_trx, osmo_bts_sysmo} [taillabel="SSH"]
osmo_gsm_tester->ofono [taillabel="DBus"]
- osmo_trx->B200 [label="USB"]
- osmo_bts_trx->{osmo_trx sysmoCell5K} [dir=both label="UDP"]
+ osmo_trx->B200 [label="UHD/USB"]
+ osmo_bts_trx->{osmo_trx sysmoCell5K} [dir=both label="TRXC+TRXD/UDP"]
osmo_bts_octphy->octphy [label="raw eth"]
{osmo_bts_sysmo nanoBTS}->OsmoNITB [label="IP"]
{B200 octphy}->OsmoNITB [label="eth" style=invis]
{osmo_bts_trx osmo_bts_octphy}->OsmoNITB
}
----
-
-.Example of how to select resources and configurations: scenarios may pick specific resources (here BTS and ARFCN), remaining requirements are picked as available (here two modems and a NITB interface)
-[graphviz]
-----
-digraph G {
- rankdir=TB;
-
- suite_scenarios [label="Suite+Scenarios selection\nsms:sysmo+band1800"]
-
- subgraph {
- rank=same;
- suite
- scenarios
- }
-
- subgraph cluster_scenarios {
- label = "Scenarios";
- u_sysmoBTS [label="Scenario: sysmo\nbts: type: osmo-bts-sysmo"]
- u_trx [label="Scenario: trx\nbts: type: osmo-bts-trx"]
- u_arfcn [label="Scenario: band1800\narfcn: band: GSM-1800"]
- }
-
- subgraph cluster_suite {
- label = "Suite: sms";
- requires [label="Requirements (suite.conf):\nmodem: times: 2\nbts\nip_address\narfcn"]
- subgraph cluster_tests {
- label = "Test Scripts (py)";
- mo_mt_sms
- etc
- }
- }
-
- subgraph cluster_resources {
- label = "Resources";
- rankdir=TB;
- nitb_addr1 [label="NITB interface addr\n10.42.42.1"]
- nitb_addr2 [label="NITB interface addr\n10.42.42.2"]
- Modem0
- Modem1
- Modem2
- sysmoBTS [label="osmo-bts-sysmo"]
- osmo_bts_trx [label="osmo-bts-trx"]
- arfcn1 [label="arfcn: 512\nband: GSM-1800"]
- arfcn2 [label="arfcn: 540\nband: GSM-1900"]
-
- arfcn1->arfcn2 [style=invis]
- nitb_addr1->nitb_addr2 [style=invis]
- Modem0 -> Modem1 -> Modem2 [style=invis]
- sysmoBTS -> osmo_bts_trx [style=invis]
- }
-
- suite_scenarios -> {suite scenarios}
- scenarios -> { u_arfcn u_sysmoBTS }
-
- suite -> requires
- requires -> Modem0
- requires -> Modem1
- requires -> sysmoBTS
- requires -> arfcn1
- requires -> nitb_addr1
-
- { u_sysmoBTS u_arfcn } -> requires [label="influences\nresource\nselection"]
-}
-----
-
-.Example of a "trial" containing binaries built by a jenkins
-[graphviz]
-----
-digraph G {
- subgraph cluster_trial {
- label = "Trial (binaries)"
- sysmo [label="osmo-bts-sysmo.build-23.tgz\n(osmo-bts-sysmo\n+ deps\ncompiled for sysmoBTS)"]
- trx [label="osmo-bts.build-5.tgz\n(osmo-bts-octphy + osmo-bts-trx\n+ deps\ncompiled for main unit)"]
- nitb [label="osmo-nitb.build-42.tgz\n(osmo-nitb\n+ deps\ncompiled for main unit)"]
- checksums [label="checksums.md5"]
-
- checksums -> {sysmo trx nitb}
- }
-}
-----
-
-=== Typical Test Script
-
-A typical single test script (part of a suite) may look like this:
-
-----
-#!/usr/bin/env python3
-from osmo_gsm_tester.testenv import *
-
-hlr = suite.hlr()
-bts = suite.bts()
-mgcpgw = suite.mgcpgw(bts_ip=bts.remote_addr())
-msc = suite.msc(hlr, mgcpgw)
-bsc = suite.bsc(msc)
-stp = suite.stp()
-ms_mo = suite.modem()
-ms_mt = suite.modem()
-
-hlr.start()
-stp.start()
-msc.start()
-mgcpgw.start()
-
-bsc.bts_add(bts)
-bsc.start()
-
-bts.start()
-
-hlr.subscriber_add(ms_mo)
-hlr.subscriber_add(ms_mt)
-
-ms_mo.connect(msc.mcc_mnc())
-ms_mt.connect(msc.mcc_mnc())
-
-ms_mo.log_info()
-ms_mt.log_info()
-
-print('waiting for modems to attach...')
-wait(ms_mo.is_connected, msc.mcc_mnc())
-wait(ms_mt.is_connected, msc.mcc_mnc())
-wait(msc.subscriber_attached, ms_mo, ms_mt)
-
-sms = ms_mo.sms_send(ms_mt)
-wait(ms_mt.sms_was_received, sms)
-----
-
-=== Resource Resolution
-
-- A global configuration 'resources.conf' defines which hardware is connected to the
- osmo-gsm-tester main unit.
-- Each suite contains a number of test scripts. The amount of resources a test
- may use is defined by the test suite's 'suite.conf'.
-- Which specific modems, BTS models, NITB IP addresses etc. are made available
- to a test run is typically determined by 'suite.conf' and a combination of scenario
- configurations -- or picked automatically if not.
-
-[[resources_conf_example]]
-=== Typical 'resources.conf'
-
-A global configuration of hardware may look like below; for details, see
-<<resources_conf>>.
-
-----
-ip_address:
-- addr: 10.42.42.2
-- addr: 10.42.42.3
-- addr: 10.42.42.4
-- addr: 10.42.42.5
-- addr: 10.42.42.6
-
-bts:
-- label: sysmoBTS 1002
- type: osmo-bts-sysmo
- ipa_unit_id: 1
- addr: 10.42.42.114
- band: GSM-1800
- ciphers:
- - a5_0
- - a5_1
- - a5_3
-
-- label: Ettus B200
- type: osmo-bts-trx
- ipa_unit_id: 6
- addr: 10.42.42.50
- band: GSM-1800
- launch_trx: true
- ciphers:
- - a5_0
- - a5_1
-
-- label: sysmoCell 5000
- type: osmo-bts-trx
- ipa_unit_id: 7
- addr: 10.42.42.51
- band: GSM-1800
- trx_remote_ip: 10.42.42.112
- ciphers:
- - a5_0
- - a5_1
-
-- label: OCTBTS 3500
- type: osmo-bts-octphy
- ipa_unit_id: 8
- addr: 10.42.42.52
- band: GSM-1800
- trx_list:
- - hw_addr: 00:0c:90:2e:80:1e
- net_device: eth1
- - hw_addr: 00:0c:90:2e:87:52
- net_device: eth1
-
-arfcn:
- - arfcn: 512
- band: GSM-1800
- - arfcn: 514
- band: GSM-1800
- - arfcn: 516
- band: GSM-1800
- - arfcn: 546
- band: GSM-1900
- - arfcn: 548
- band: GSM-1900
-
-modem:
-- label: sierra_1
- path: '/sierra_1'
- imsi: '901700000009031'
- ki: '80A37E6FDEA931EAC92FFA5F671EFEAD'
- auth_algo: 'xor'
- ciphers:
- - a5_0
- - a5_1
- features:
- - 'sms'
- - 'voice'
-
-- label: gobi_0
- path: '/gobi_0'
- imsi: '901700000009030'
- ki: 'BB70807226393CDBAC8DD3439FF54252'
- auth_algo: 'xor'
- ciphers:
- - a5_0
- - a5_1
- features:
- - 'sms'
-----
-
-=== Typical 'suites/*/suite.conf'
-
-The configuration that reserves a number of resources for a test suite may look
-like this:
-
-----
-resources:
- ip_address:
- - times: 1
- bts:
- - times: 1
- modem:
- - times: 2
- features:
- - sms
-----
-
-It may also request e.g. specific BTS models, but this is typically left to
-scenario configurations.
-
-=== Typical 'scenarios/*.conf'
-
-For a suite as above run as-is, any available resources are picked. This may be
-combined with any number of scenario definitions to constrain which specific
-resources should be used, e.g.:
-
-----
-resources:
- bts:
- - type: osmo-bts-sysmo
-----
-
-Which 'ip_address' or 'modem' is used in particular doesn't really matter, so
-it can be left up to the osmo-gsm-tester to pick these automatically.
-
-Any number of such scenario configurations can be combined in the form
-'<suite_name>:<scenario>+<scenario>+...', e.g. 'my_suite:sysmo+tch_f+amr'.
-
-=== Typical Invocations
-
-Each invocation of osmo-gsm-tester deploys a set of pre-compiled binaries for
-the Osmocom core network as well as for the Osmocom based BTS models. To create
-such a set of binaries, see <<trials>>.
-
-Examples for launching test trials:
-
-- Run the default suites (see <<default_suites>>) on a given set of binaries:
-
-----
-osmo-gsm-tester.py path/to/my-trial
-----
-
-- Run an explicit choice of 'suite:scenario' combinations:
-
-----
-osmo-gsm-tester.py path/to/my-trial -s sms:sysmo -s sms:trx -s sms:nanobts
-----
-
-- Run one 'suite:scenario' combination, setting log level to 'debug' and
- enabling logging of full python tracebacks, and also only run just the
- 'mo_mt_sms.py' test from the suite, e.g. to investigate a test failure:
-
-----
-osmo-gsm-tester.py path/to/my-trial -s sms:sysmo -l dbg -T -t mo_mt
-----
-
-A test script may also be run step-by-step in a python debugger, see
-<<debugging>>.
-
-=== Resource Reservation for Concurrent Trials
-
-While a test suite runs, the used resources are noted in a global state
-directory in a reserved-resources file. This way, any number of trials may be
-run consecutively without resource conflicts. Any test trial will only use
-resources that are currently not reserved by any other test suite. The
-reservation state is human readable.
-
-The global state directory is protected by a file lock to allow access by
-separate processes.
-
-Also, the binaries from a trial are never installed system-wide, but are run
-with a specific 'LD_LIBRARY_PATH' pointing at the trial's 'inst', so that
-several trials can run consecutively without conflicting binary versions. For
-some specific binaries which require extra permissions (such as osmo-bts-octphy
-requiring 'CAP_NET_RAW'), 'patchelf' program is used to modify the binary
-'RPATH' field instead because the OS dynamic linker skips 'LD_LIBRARY_PATH' for
-binaries with special permissions.
-
-Once a test suite run is complete, all its reserved resources are torn down (if
-the test scripts have not done so already), and the reservations are released
-automatically.
-
-If required resources are unavailable, the test trial fails. For consecutive
-test trials, a test run needs to either wait for resources to become available,
-or test suites need to be scheduled to make sense. (*<- TODO*)