doc/manuals/chapters/intro.adoc

== Introduction

{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 to
work for other technologies, setups and projects. It can be used for instance to
test a 3G or 4G network.

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

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

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 {
	rankdir=LR;
	jenkins
	subgraph cluster_gsm_hardware {
		label = "GSM Hardware";
		style=dotted

		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]
		octphy [label="Octasic octphy BTS" shape=box]
		nanoBTS [label="ip.access nanoBTS" shape=box]
		rf_distribution [label="RF distribution"]

		{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_bts_trx [label="osmo-bts-trx"]
		osmo_bts_octphy [label="osmo-bts-octphy"]
		OsmoNITB [label="BSC + Core Network\n(Osmo{NITB,MSC,BSC,HLR,...})"]
	  }
	}


	jenkins->osmo_gsm_tester [label="trial\n(binaries)"]
	osmo_gsm_tester->jenkins [label="results"]
	ofono->{modem0 modem1} [label="QMI/USB"]
	osmo_gsm_tester->{OsmoNITB osmo_bts_trx osmo_bts_octphy}
	osmo_gsm_tester->{osmo_trx, osmo_bts_sysmo} [taillabel="SSH"]
	osmo_gsm_tester->ofono [taillabel="DBus"]
	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
}
----