Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 1 | == Introduction |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 2 | |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 3 | {app-name} is a software to run automated tests on real GSM hardware, |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 4 | foremost to verify that ongoing Osmocom software development continues to work |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 5 | with various BTS models, while being flexibly configurable and extendable to |
| 6 | work for other technologies, setups and projects. It can be used for instance to |
| 7 | test a 3G or 4G network. |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 8 | |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 9 | {app-name} (python3 process) runs on a host (general purpose computer) named |
| 10 | the 'main unit'. It may optionally be connected to any number of 'slave units', |
| 11 | which {app-name} may use to orchestrate processes remotely, usually through SSH. |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 12 | |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 13 | Hardware devices such as BTS, SDRs, modems, smart plugs, etc. are then connected |
| 14 | to either the main unit or slaves units via IP, raw ethernet, USB or any other |
| 15 | meansĀ· |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 16 | |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 17 | The modems and BTS instances' RF transceivers are typically wired directly to |
| 18 | each other via RF distribution chambers to bypass the air medium and avoid |
| 19 | disturbing real production cellular networks. Furthermore, the setup may include |
| 20 | adjustable RF attenuators to model various distances between modems and base |
| 21 | stations. |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 22 | |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 23 | Each of these devices, having each a different physical setup and configuration, |
| 24 | supported features, attributes, etc., is referred in {app-name} terminology as a |
| 25 | _resource_. Each _resource_ is an instance of _resource class_. A |
| 26 | _resource_class_ may be for instance a _modem_ or a _bts_. For instance, an |
| 27 | {app-name} setup may have 2 _modem_ instances and 1 _bts_ instances. Each of |
| 28 | these _resources_ are listed and described in configuration files passed to |
| 29 | {app-name}, which maintains a pool of _resources_ (available, in use, etc.). |
| 30 | |
| 31 | {app-name} typically receives from a jenkins build service the software or |
| 32 | firmware binary packages to be used and tested. {app-name} then launches a |
| 33 | specific set of testsuites which, in turn, contain each a set of python test |
| 34 | scripts. Each test uses the _testenv_ API provided by {app-name} to configure, |
| 35 | launch and manage the different nodes and processes from the provided binary |
| 36 | packages to form a complete ad-hoc GSM network. |
| 37 | |
| 38 | Testsuites themselves contain configuration files to list how many resources it |
| 39 | requires to run its tests. It also provides means to _filter_ which kind of |
| 40 | _resources_ will be needed based on their attributes. This allows, for instance, |
| 41 | asking {app-name} to provide a _modem_ supporting GPRS, or to provide a specific |
| 42 | model of _bts_ such as a nanoBTS. Testsuites also allow receiving _modifiers_, |
| 43 | which overwrite some of the default values that {app-name} itself or different |
| 44 | _resources_ use. |
| 45 | |
| 46 | Moreover, one may want to run the same testsuite several tiems, each with |
| 47 | different set of _resources_. For instance, one may want to run a testsuite with |
| 48 | a sysmoBTS and later with a nanoBTS. This is supported by leaving the testsuite |
| 49 | configuration generic enough and then passing _scenarios_ to it, which allow |
| 50 | applying extra _filters_ or _modifiers_. Scenarios can also be combined to |
| 51 | filter further or to apply further modifications. |
| 52 | |
| 53 | .Sample osmo-gsm-tester node 2G setup |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 54 | [graphviz] |
| 55 | ---- |
| 56 | digraph G { |
| 57 | rankdir=LR; |
| 58 | jenkins |
| 59 | subgraph cluster_gsm_hardware { |
| 60 | label = "GSM Hardware"; |
| 61 | style=dotted |
| 62 | |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 63 | modem0 [shape=box label="Modem (Quectel EC20)"] |
| 64 | modem1 [shape=box label="Modems (SierraWireless MC7455)"] |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 65 | osmo_bts_sysmo [label="sysmocom sysmoBTS\nrunning osmo-bts-sysmo" shape=box] |
| 66 | B200 [label="Ettus B200" shape=box] |
Pau Espin Pedrol | 48d2564 | 2017-11-02 14:03:58 +0100 | [diff] [blame] | 67 | sysmoCell5K [label="sysmocom sysmoCell5000" shape=box] |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 68 | octphy [label="Octasic octphy BTS" shape=box] |
| 69 | nanoBTS [label="ip.access nanoBTS" shape=box] |
| 70 | rf_distribution [label="RF distribution"] |
| 71 | |
Pau Espin Pedrol | 48d2564 | 2017-11-02 14:03:58 +0100 | [diff] [blame] | 72 | {modem0 modem1 osmo_bts_sysmo B200 octphy nanoBTS sysmoCell5K}->rf_distribution [dir=both arrowhead="curve" arrowtail="curve"] |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 73 | } |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 74 | subgraph cluster_slave_unit { |
| 75 | label = "Slave Unit" |
| 76 | osmo_trx [label="osmo-trx"] |
| 77 | } |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 78 | subgraph cluster_main_unit { |
| 79 | label = "Main Unit" |
| 80 | osmo_gsm_tester [label="Osmo-GSM-Tester\ntest suites\n& scenarios"] |
Neels Hofmeyr | 73207e1 | 2017-05-05 02:50:45 +0200 | [diff] [blame] | 81 | subgraph { |
| 82 | rank=same |
| 83 | ofono [label="ofono daemon"] |
Pau Espin Pedrol | 48d2564 | 2017-11-02 14:03:58 +0100 | [diff] [blame] | 84 | osmo_bts_trx [label="osmo-bts-trx"] |
Neels Hofmeyr | 73207e1 | 2017-05-05 02:50:45 +0200 | [diff] [blame] | 85 | osmo_bts_octphy [label="osmo-bts-octphy"] |
Pau Espin Pedrol | 48d2564 | 2017-11-02 14:03:58 +0100 | [diff] [blame] | 86 | OsmoNITB [label="BSC + Core Network\n(Osmo{NITB,MSC,BSC,HLR,...})"] |
Neels Hofmeyr | 73207e1 | 2017-05-05 02:50:45 +0200 | [diff] [blame] | 87 | } |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 88 | } |
| 89 | |
| 90 | |
| 91 | jenkins->osmo_gsm_tester [label="trial\n(binaries)"] |
| 92 | osmo_gsm_tester->jenkins [label="results"] |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 93 | ofono->{modem0 modem1} [label="QMI/USB"] |
Pau Espin Pedrol | 48d2564 | 2017-11-02 14:03:58 +0100 | [diff] [blame] | 94 | osmo_gsm_tester->{OsmoNITB osmo_bts_trx osmo_bts_octphy} |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 95 | osmo_gsm_tester->{osmo_trx, osmo_bts_sysmo} [taillabel="SSH"] |
Pau Espin Pedrol | 48d2564 | 2017-11-02 14:03:58 +0100 | [diff] [blame] | 96 | osmo_gsm_tester->ofono [taillabel="DBus"] |
Pau Espin Pedrol | 7e0b2dd | 2020-03-10 11:46:39 +0100 | [diff] [blame] | 97 | osmo_trx->B200 [label="UHD/USB"] |
| 98 | osmo_bts_trx->{osmo_trx sysmoCell5K} [dir=both label="TRXC+TRXD/UDP"] |
Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 99 | osmo_bts_octphy->octphy [label="raw eth"] |
Pau Espin Pedrol | 48d2564 | 2017-11-02 14:03:58 +0100 | [diff] [blame] | 100 | {osmo_bts_sysmo nanoBTS}->OsmoNITB [label="IP"] |
Neels Hofmeyr | 73207e1 | 2017-05-05 02:50:45 +0200 | [diff] [blame] | 101 | {B200 octphy}->OsmoNITB [label="eth" style=invis] |
| 102 | {osmo_bts_trx osmo_bts_octphy}->OsmoNITB |
| 103 | } |
| 104 | ---- |