diff --git a/example/README.txt b/example/README.txt
new file mode 100644
index 0000000..76567f2
--- /dev/null
+++ b/example/README.txt
@@ -0,0 +1,30 @@
+This a real gsm test suite configured and ready to use.
+The only thing missing is a trial dir containing binaries.
+
+You can point osmo-gsm-tester.py at this config using the OSMO_GSM_TESTER_CONF
+environment variable:
+
+    export OSMO_GSM_TESTER_CONF="$PWD"
+
+When there is no OSMO_GSM_TESTER_CONF set, osmo-gsm-tester will instead look
+for conf files in several locations like ~/.config/osmo-gsm-tester,
+/usr/local/etc/osmo-gsm-tester, /etc/osmo-gsm-tester.
+
+If you have your trial with binary tar archives in ~/my_trial
+you can run the suite for example like this:
+
+    osmo-gsm-tester.py ~/my_trial
+
+Specifically, from this dir:
+
+    OSMO_GSM_TESTER_CONF="$PWD" ../src/osmo-gsm-tester.py ~/my_trial
+
+Alternatively you can setup this example as permanent config using something
+like:
+
+    mkdir -p ~/.config
+    ln -s "$PWD" ~/.config/osmo-gsm-tester
+
+A ./state dir will be created to store the current osmo-gsm-tester state. If
+you prefer not to write to $PWD, set up an own configuration pointing at a
+different path (see paths.conf: 'state_dir').
diff --git a/example/default-suites.conf b/example/default-suites.conf
new file mode 100644
index 0000000..601076a
--- /dev/null
+++ b/example/default-suites.conf
@@ -0,0 +1 @@
+- sms:sysmo
diff --git a/example/defaults.conf b/example/defaults.conf
new file mode 100644
index 0000000..006ff7e
--- /dev/null
+++ b/example/defaults.conf
@@ -0,0 +1,26 @@
+nitb:
+  net:
+    mcc: 901
+    mnc: 70
+    short_name: osmo-gsm-tester
+    long_name: osmo-gsm-tester
+    auth_policy: closed
+    encryption: a5 0
+
+nitb_bts:
+  location_area_code: 23
+  base_station_id_code: 63
+  stream_id: 255
+  osmobsc_bts_type: sysmobts
+  trx_list:
+  - max_power_red: 0
+    arfcn: 868
+    timeslot_list:
+    - phys_chan_config: CCCH+SDCCH4
+    - phys_chan_config: SDCCH8
+    - phys_chan_config: TCH/F_TCH/H_PDCH
+    - phys_chan_config: TCH/F_TCH/H_PDCH
+    - phys_chan_config: TCH/F_TCH/H_PDCH
+    - phys_chan_config: TCH/F_TCH/H_PDCH
+    - phys_chan_config: TCH/F_TCH/H_PDCH
+    - phys_chan_config: TCH/F_TCH/H_PDCH
diff --git a/example/paths.conf b/example/paths.conf
new file mode 100644
index 0000000..bb7316c
--- /dev/null
+++ b/example/paths.conf
@@ -0,0 +1,3 @@
+state_dir: './state'
+suites_dir: './suites'
+scenarios_dir: './scenarios'
diff --git a/example/resources.conf b/example/resources.conf
new file mode 100644
index 0000000..bb6181f
--- /dev/null
+++ b/example/resources.conf
@@ -0,0 +1,80 @@
+# all hardware and interfaces available to this osmo-gsm-tester
+
+nitb_iface:
+- addr: 10.42.42.1
+- addr: 10.42.42.2
+- addr: 10.42.42.3
+
+bts:
+- label: sysmoBTS 1002
+  type: osmo-bts-sysmo
+  ipa_unit_id: 1
+  addr: 10.42.42.114
+  band: GSM-1800
+
+- label: octBTS 3000
+  type: osmo-bts-octphy
+  ipa_unit_id: 5
+  addr: 10.42.42.115
+  band: GSM-1800
+  trx_list:
+  - hw_addr: 00:0c:90:32:b5:8a
+    net_device: eth0.2342
+
+- label: Ettus B210
+  type: osmo-bts-trx
+  ipa_unit_id: 6
+  addr: 10.42.42.116
+  band: GSM-1800
+
+- label: nanoBTS 1900
+  type: nanobts
+  ipa_unit_id: 1902
+  addr: 10.42.42.190
+  band: GSM-1900
+  trx_list:
+  - hw_addr: 00:02:95:00:41:b3
+
+arfcn:
+  - arfcn: 512
+    band: GSM-1800
+  - arfcn: 514
+    band: GSM-1800
+  - arfcn: 516
+    band: GSM-1800
+  - arfcn: 518
+    band: GSM-1800
+  - arfcn: 520
+    band: GSM-1800
+
+  - arfcn: 540
+    band: GSM-1900
+  - arfcn: 542
+    band: GSM-1900
+  - arfcn: 544
+    band: GSM-1900
+  - arfcn: 546
+    band: GSM-1900
+  - arfcn: 548
+    band: GSM-1900
+
+modem:
+- label: sierra_1
+  path: '/sierra_1'
+  imsi: '901700000009031'
+  ki: '80A37E6FDEA931EAC92FFA5F671EFEAD'
+
+- label: sierra_2
+  path: '/sierra_2'
+  imsi: '901700000009029'
+  ki: '00969E283349D354A8239E877F2E0866'
+
+- label: gobi_0
+  path: '/gobi_0'
+  imsi: '901700000009030'
+  ki: 'BB70807226393CDBAC8DD3439FF54252'
+
+- label: gobi_3
+  path: '/sierra_3'
+  imsi: '901700000009032'
+  ki: '2F70DCA43C45ACB97E947FDD0C7CA30A'
diff --git a/example/scenarios/octphy.conf b/example/scenarios/octphy.conf
new file mode 100644
index 0000000..3a419e8
--- /dev/null
+++ b/example/scenarios/octphy.conf
@@ -0,0 +1,3 @@
+resources:
+  bts:
+  - type: osmo-bts-octphy
diff --git a/example/scenarios/sysmo.conf b/example/scenarios/sysmo.conf
new file mode 100644
index 0000000..624758b
--- /dev/null
+++ b/example/scenarios/sysmo.conf
@@ -0,0 +1,3 @@
+resources:
+  bts:
+  - type: osmo-bts-sysmo
diff --git a/example/scenarios/trx.conf b/example/scenarios/trx.conf
new file mode 100644
index 0000000..f1d6d13
--- /dev/null
+++ b/example/scenarios/trx.conf
@@ -0,0 +1,3 @@
+resources:
+  bts:
+  - type: osmo-bts-trx
diff --git a/example/suites/sms/mo_mt_sms.py b/example/suites/sms/mo_mt_sms.py
new file mode 100755
index 0000000..7176197
--- /dev/null
+++ b/example/suites/sms/mo_mt_sms.py
@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+from osmo_gsm_tester.test import *
+
+print('use resources...')
+nitb = suite.nitb()
+bts = suite.bts()
+ms_mo = suite.modem()
+ms_mt = suite.modem()
+
+print('start nitb and bts...')
+nitb.bts_add(bts)
+nitb.start()
+sleep(1)
+assert nitb.running()
+bts.start()
+
+nitb.subscriber_add(ms_mo)
+nitb.subscriber_add(ms_mt)
+
+ms_mo.connect(nitb)
+ms_mt.connect(nitb)
+print(ms_mo.properties())
+print(ms_mt.properties())
+wait(nitb.subscriber_attached, ms_mo, ms_mt)
+
+sms = ms_mo.sms_send(ms_mt.msisdn)
+wait(ms_mt.sms_was_received, sms)
diff --git a/example/suites/sms/suite.conf b/example/suites/sms/suite.conf
new file mode 100644
index 0000000..4a03379
--- /dev/null
+++ b/example/suites/sms/suite.conf
@@ -0,0 +1,10 @@
+resources:
+  nitb_iface:
+  - times: 1
+  bts:
+  - times: 1
+  modem:
+  - times: 2
+
+defaults:
+  timeout: 60s