cellular-infrastructure
/
osmo-bsc
mirror of https://gerrit.osmocom.org/osmo-bsc
9
0
Fork 0
Code Issues Releases Wiki Activity

Merge history from osmo-gsm-manuals.git 

Change-Id: I9ff481784ba8c6334b1e57b1f64dfc9262e6d0e2
This commit is contained in:
Neels Hofmeyr 2018-11-27 17:14:47 +01:00
parent 369fba25de 27683cbe13
commit 5c55d4933d
35 changed files with 8016 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
doc/manuals/Makefile Normal file
View File

@ -0,0 +1,11 @@
TOPDIR = ..
ASCIIDOC = osmobsc-usermanual.adoc osmux-reference.adoc aoip-mgw-options.adoc
include $(TOPDIR)/build/Makefile.asciidoc.inc
osmobsc-usermanual.pdf: chapters/*.adoc chapters/*.dot
aoip-mgw-options.pdf: aoip-mgw-options.adoc mgw/*.msc
VTY_REFERENCE = osmobsc-vty-reference.xml
include $(TOPDIR)/build/Makefile.vty-reference.inc
include $(TOPDIR)/build/Makefile.common.inc

47
doc/manuals/aoip-mgw-options-docinfo.xml Normal file
View File

@ -0,0 +1,47 @@
<revhistory>
<revision>
<revnumber>0.1</revnumber>
<date>31 May 2017</date>
<authorinitials>Harald Welte</authorinitials>
<revremark>
Initial version of the proposal for internal discussion.
</revremark>
</revision>
</revhistory>
<authorgroup>
<author>
<firstname>Harald</firstname>
<surname>Welte</surname>
<email>hwelte@sysmocom.de</email>
<authorinitials>HW</authorinitials>
<affiliation>
<shortaffil>sysmocom</shortaffil>
<orgname>sysmocom - s.f.m.c. GmbH</orgname>
<jobtitle>Managing Director</jobtitle>
</affiliation>
</author>
</authorgroup>
<copyright>
<year>2017</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 the Invariant Sections being just 'Foreword',
'Acknowledgements' and 'Preface', with 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>

77
doc/manuals/aoip-mgw-options.adoc Normal file
View File

@ -0,0 +1,77 @@
= OsmoBSC A / SCCPlite / 3GPP AoIP Options
== Introduction
This document serves as a paper to illustrate the different
configurations of OsmoBSC in terms of integration with BTSs and MSCs.
The document should accompany us in the 2017 development cycle which
includes the _death of the NITB_, i.e. the move away from OsmoNITB to
having OsmoBSC in all configurations, whether with a
proprietary/external MSC or with OsmoMSC.
Particular attention is spent on the user plane, including aspects
such as
* user plane transport address handling
* use of MGCP (Media Gateway Control Protocol)
* the (required) evolution of `osmo-bsc_mgcp`
* not loosing classic TDM (E1/T1) BTS support when moving from
OsmoNITB to split OsmoBSC + OsmoMSC setup
== Overview
=== Classic GSM RAN with E1 based Abis and E1 A
This configuration was actually never supported by OpenBSC, as E1 BTS
support was so far for NITB only, but not for OsmoBSC.
[mscgen]
----
include::mgw/classic-bsc.msc[]
----
=== OsmoBSC 2010-2017: IPA-style A over SCCPlite
This configuration was introduced as early as 2010 in OpenBSC. It
allowed the use of IP based BTSs (ip.access nanoBTS as well as all the
OsmoBTS supported BTS models) in combination with third-party MSCs
implementing a pre-standard, proprietary way of transporting the A
interface over IP at a time where the 3GPP specifications only allowed
classic TDM transport.
[mscgen]
----
include::mgw/osmo-bsc-old-sccplite.msc[]
----
=== OsmoBSC 2017+: 3GPP AoIP + Abis/IP
Release 7 of 3GPP included an official specification on how an
interoperable A-over-IP (AoIP) interface shall look like.
As more modern MSCs at operators tend to favor implementing 3GPP AoIP
rather than the proprietary SCCPlite based A interface, it becomes
neccessary for OsmoBSC to support this.
At the same time, for compatibility reasons, the classic SCCPlite
support shall be kept, if possible with reasonable effort.
[mscgen]
----
include::mgw/osmo-bsc-new-mgw.msc[]
----
=== OsmoBSC 2017+: 3GPP AoIP + Abis/E1
Since OsmoNITB will soon be deprecated, we will use OsmoBSC in all
Osmocom GSM ntework setups, requiring the support for classic E1/T1
based BTSs from OsmoBSC.
[mscgen]
----
include::mgw/osmo-bsc-new-mgw-e1.msc[]
----

281
doc/manuals/chapters/bts-examples.adoc Normal file
View File

@ -0,0 +1,281 @@
[[bts-examples]]
== OsmoNITB example configuration files
The `openbsc/doc/examples/osmo-nitb` directory in the OpenBSC source
tree contains a collection of example configuration files, sorted by BTS
type.
This chapter is illustrating some excerpts from those examples
[[bts_example_bs11]]
=== Example configuration for OsmoNITB with one dual-TRX BS-11
.OsmoNITB with BS11, 2 TRX, no frequency hopping
====
----
e1_input
e1_line 0 driver misdn
network
network country code 1
mobile network code 1
short name OpenBSC
long name OpenBSC
timer t3101 10
timer t3113 60
bts 0
type bs11 <1>
band GSM900
cell_identity 1
location_area_code 1
training_sequence_code 7
base_station_id_code 63
oml e1 line 0 timeslot 1 sub-slot full <2>
oml e1 tei 25 <3>
trx 0
arfcn 121
max_power_red 0
rsl e1 line 0 timeslot 1 sub-slot full <4>
rsl e1 tei 1 <5>
timeslot 0
phys_chan_config CCCH+SDCCH4
e1 line 0 timeslot 1 sub-slot full
timeslot 1
phys_chan_config TCH/F
e1 line 0 timeslot 2 sub-slot 1 <6>
timeslot 2
phys_chan_config TCH/F
e1 line 0 timeslot 2 sub-slot 2
timeslot 3
phys_chan_config TCH/F
e1 line 0 timeslot 2 sub-slot 3
timeslot 4
phys_chan_config TCH/F
e1 line 0 timeslot 3 sub-slot 0
timeslot 5
phys_chan_config TCH/F
e1 line 0 timeslot 3 sub-slot 1
timeslot 6
phys_chan_config TCH/F
e1 line 0 timeslot 3 sub-slot 2
timeslot 7
phys_chan_config TCH/F
e1 line 0 timeslot 3 sub-slot 3
trx 1
arfcn 123
max_power_red 0
rsl e1 line 0 timeslot 1 sub-slot full <4>
rsl e1 tei 2 <5>
timeslot 0
phys_chan_config TCH/F
e1 line 0 timeslot 4 sub-slot 0 <6>
timeslot 1
phys_chan_config TCH/F
e1 line 0 timeslot 4 sub-slot 1
timeslot 2
phys_chan_config TCH/F
e1 line 0 timeslot 4 sub-slot 2
timeslot 3
phys_chan_config TCH/F
e1 line 0 timeslot 4 sub-slot 3
timeslot 4
phys_chan_config TCH/F
e1 line 0 timeslot 5 sub-slot 0
timeslot 5
phys_chan_config TCH/F
e1 line 0 timeslot 5 sub-slot 1
timeslot 6
phys_chan_config TCH/F
e1 line 0 timeslot 5 sub-slot 2
timeslot 7
phys_chan_config TCH/F
e1 line 0 timeslot 5 sub-slot 3
----
====
<1> The BTS type must be set to __bs11__
<2> The OML E1 timeslot needs to be identical with what was on the BTS side using LMT.
<3> The OML TEI value needs to be identical with what was configured on the BTS side using LMT.
<4> The RSL E1 timeslot can be identical for all TRX.
<5> The RSL TEI values __must__ be different if multiple TRX share one E1 signalling timeslot.
<6> The TCH all need to be allocated one 16k sub-slot on the E1
[[bts_example_nbts]]
=== Example configuration for OsmoNITB with one single-TRX nanoBTS
.OsmoNITB with one single-TRX nanoBTS
====
----
e1_input
e1_line 0 driver ipa <1>
network
network country code 1
mobile network code 1
short name OpenBSC
long name OpenBSC
auth policy closed
location updating reject cause 13
encryption a5 0
neci 1
rrlp mode none
mm info 1
handover 0
bts 0
type nanobts <2>
band DCS1800 <3>
cell_identity 0
location_area_code 1
training_sequence_code 7
base_station_id_code 63
ms max power 15
cell reselection hysteresis 4
rxlev access min 0
channel allocator ascending
rach tx integer 9
rach max transmission 7
ip.access unit_id 1801 0 <4>
oml ip.access stream_id 255 line 0
gprs mode none
trx 0
rf_locked 0
arfcn 871 <5>
nominal power 23
max_power_red 20 <6>
rsl e1 tei 0
timeslot 0
phys_chan_config CCCH+SDCCH4
timeslot 1
phys_chan_config SDCCH8
timeslot 2
phys_chan_config TCH/F
timeslot 3
phys_chan_config TCH/F
timeslot 4
phys_chan_config TCH/F
timeslot 5
phys_chan_config TCH/F
timeslot 6
phys_chan_config TCH/F
timeslot 7
phys_chan_config TCH/F
----
====
<1> You have to configure one virtual E1 line with the
IPA driver in order to use Abis/IP. One e1_line is
sufficient for any number of A-bis/IP BTSs, there is no
limit like in physical E1 lines.
<2> The BTS type must be set using `type nanobts`
<3> The GSM band must be set according to the BTS hardware.
<4> The IPA Unit ID parameter must be set to what has been configured on
the BTS side using the __BTS Manager__ or `ipaccess-config`.
<5> The ARFCN of the BTS.
<6> All known nanoBTS units have a nominal transmit power of 23 dBm. If
a `max_power_red` of 20 (dB) is configured, the resulting output
power at the BTS Tx port is 23 - 20 = 3 dBm.
[NOTE]
====
The `nominal_power` setting does __not__ influence the transmitted power
to the BTS! It is a setting by which the system administrator tells the
BSC about the nominal output power of the BTS. The BSC uses this as
basis for calculations.
====
[[bts_example_nbts_multi]]
=== Example configuration for OsmoNITB with multi-TRX nanoBTS
.OsmoNITB configured for dual-TRX (stacked) nanoBTS
====
----
e1_input
e1_line 0 driver ipa
network
network country code 1
mobile network code 1
short name OpenBSC
long name OpenBSC
auth policy closed
location updating reject cause 13
encryption a5 0
neci 1
rrlp mode none
mm info 0
handover 0
bts 0
type nanobts
band DCS1800
cell_identity 0
location_area_code 1
training_sequence_code 7
base_station_id_code 63
ms max power 15
cell reselection hysteresis 4
rxlev access min 0
channel allocator ascending
rach tx integer 9
rach max transmission 7
ip.access unit_id 1800 0 <1>
oml ip.access stream_id 255 line 0
gprs mode none
trx 0
rf_locked 0
arfcn 871
nominal power 23
max_power_red 0
rsl e1 tei 0
timeslot 0
phys_chan_config CCCH+SDCCH4
timeslot 1
phys_chan_config SDCCH8
timeslot 2
phys_chan_config TCH/F
timeslot 3
phys_chan_config TCH/F
timeslot 4
phys_chan_config TCH/F
timeslot 5
phys_chan_config TCH/F
timeslot 6
phys_chan_config TCH/F
timeslot 7
phys_chan_config TCH/F
trx 1
rf_locked 0
arfcn 873
nominal power 23
max_power_red 0
rsl e1 tei 0
timeslot 0
phys_chan_config SDCCH8
timeslot 1
phys_chan_config TCH/F
timeslot 2
phys_chan_config TCH/F
timeslot 3
phys_chan_config TCH/F
timeslot 4
phys_chan_config TCH/F
timeslot 5
phys_chan_config TCH/F
timeslot 6
phys_chan_config TCH/F
timeslot 7
phys_chan_config TCH/F
----
====
<1> In this example, the IPA Unit ID is specified as `1800 0`. Thus, the
first nanoBTS unit (`trx 0`) needs to be configured to 1800/0/0 and
the second nanoBTS unit (`trx 1`) needs to be configured to 1800/0/1.
You can configure the BTS unit IDs using the `ipaccess-config`
utility included in OpenBSC.
[NOTE]
====
For building a multi-TRX setup, you also need to connect the TIB cables
between the two nanoBTS units, as well as the coaxial/RF AUX cabling.
====

100
doc/manuals/chapters/control.adoc Normal file
View File

@ -0,0 +1,100 @@
[[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 OsmoBSC. The commands starting with prefix
"bts.N." are specific to a certain BTS so N have to be replaced with BTS
number when issuing command e. g. "bts.1.channel-load". Similarly the
TRX-specific commands are additionally prefixed with TRX number e. g.
"bts.1.trx.2.arfcn".
.Variables available over control interface
[options="header",width="100%",cols="20%,5%,5%,50%,20%"]
|===
|Name|Access|Trap|Value|Comment
|msc_connection_status|RO|Yes|"connected", "disconnected"|Indicate the status of connection to MSC.
|bts_connection_status|RO|Yes|"connected", "disconnected"|Indicate the status of connection to BTS.
|location|RW|Yes|"<unixtime>,(invalid\|fix2d\|fix3d),<lat>,<lon>,<height>"|Set/Get location data.
|timezone|RW|No|"<hours>,<mins>,<dst>", "off"|-19 \<= hours \<= 19, mins in {0, 15, 30, 45}, and 0 \<= dst \<= 2
|apply-configuration|WO|No|"restart"|Restart all BTSes.
|mnc|RW|No|"<mnc>"|Set/Get MNC (value between (0, 999)).
|mcc|RW|No|"<mcc>"|Set/Get MCC (value between (1, 999)).
|short-name|RW|No|"<name>"|Set/Get network's short name.
|long-name|RW|No|"<name>"|Set/Get network's long name.
|mcc-mnc-apply|WO|No|"<mcc>,<mnc>"|Apply new MCC/MNC values if different from currently used one.
|notification|WO|Yes|Arbitrary value| See <<notif>> for details.
|inform-msc-v1|WO|Yes|Arbitrary value| See <<infomsc>> for details.
|ussd-notify-v1|WO|No|"<cic>,<alert>,<text>"| See <<ussdnot>> for details.
|rf_locked|RW|No|"0","1"|See <<rfl>> for details.
|number-of-bts|RO|No|"<num>"|Get number of configured BTS.
|bts.N.location-area-code|RW|No|"<lac>"|Set/Get LAC (value between (0, 65535)).
|bts.N.cell-identity|RW|No|"<id>"|Set/Get Cell Identity (value between (0, 65535)).
|bts.N.apply-configuration|WO|No|Ignored|Restart BTS via OML.
|bts.N.send-new-system-informations|WO|No|Ignored|Regenerate System Information messages for given BTS.
|bts.N.channel-load|RO|No|"<name>,<used>,<total>"|See <<chanlo>> for details.
|bts.N.oml-connection-state|RO|No|"connected", "disconnected", "degraded"|Indicate the status of OML connection of BTS.
|bts.N.oml-uptime|RO|No|<uptime>|Return OML link uptime in seconds.
|bts.N.gprs-mode|RW|No|"<mode>"|See <<gprsm>> for details.
|bts.N.rf_state|RO|No|"<oper>,<admin>,<pol>"|See <<rfs>> for details.
|bts.N.trx.M.arfcn|RW|No|"<arfcn>"|Set/Get ARFCN (value between (0, 1023)).
|bts.N.trx.M.max-power-reduction|RW|No|"<mpr>"|See <<mpr>> for details.
|===
[[notif]]
=== notification
Setting this variable initiate TRAP "notification" to all the clients connected
to control interface with the value supplied in SET operation. This is not
intended to be used outside of local systems.
[[infomsc]]
=== inform-msc-v1
Setting this variable initiate TRAP "inform-msc-v1" to all connected MSCs
control interfaces with the value supplied in SET operation.
[[ussdnot]]
=== ussd-notify-v1
Setting this variable will send USSD Notify message to subscriber specified in
command parameters with the text specified in command parameters.
[[chanlo]]
=== channel-load
Obtain channel load for given BTS. Returns concatenated set of triplets
("<name>,<used>,<total>") for all channel types configured on the BTS. The
"<name>" is the channel type. The "<used>" is the number of channels of that
type currently in use. The "<total>" is the number of channels of that type
configured on the BTS.
[[gprsm]]
=== gprs-mode
Set/Get the GPRS mode of the BTS. One of the following is
accepted/returned: "none", "gprs", "egprs".
[[rfs]]
=== rf_state
Following triplet is returned: "<oper>,<admin>,<pol>". The "<oper>" might be
"operational" or "inoperational" representing different operational states. The
"<admin>" might be "locked" or "unlocked" representing administrative status.
The "<pol>" might be "off", "on", "grace" or "unknown" representing different
RF policies.
[[rfl]]
=== rf_locked
Set/Get RF locked status. The GET operation will return either "0" or "1"
depending on the RF lock status. The SET operation will set RF lock status if
RF Ctrl is enabled in the BSC Configuration.
[[mpr]]
=== max-power-reduction
Set/Get the value of maximum power reduction. Even values between 0 and 22 are
accepted.
FIXME: add variables defined in src/ctrl/control_if.c?

4
doc/manuals/chapters/counters.adoc Normal file
View File

@ -0,0 +1,4 @@
[[counters]]
== Counters
include::./counters_generated.adoc[]

76
doc/manuals/chapters/counters_generated.adoc Normal file
View File

@ -0,0 +1,76 @@
// autogenerated by show asciidoc counters
These counters and their description based on OsmoBSC (OsmoBSC).
// generating tables for rate_ctr_group
// rate_ctr_group table E1 Input subsystem
.e1inp - E1 Input subsystem
[options="header"]
|===
| Name | Reference | Description
| hdlc:abort | <<e1inp_hdlc:abort>> | HDLC abort
| hdlc:bad_fcs | <<e1inp_hdlc:bad_fcs>> | HLDC Bad FCS
| hdlc:overrun | <<e1inp_hdlc:overrun>> | HDLC Overrun
| alarm | <<e1inp_alarm>> | Alarm
| removed | <<e1inp_removed>> | Line removed
|===
// rate_ctr_group table base station controller
.bsc - base station controller
[options="header"]
|===
| Name | Reference | Description
| chreq:total | <<bsc_chreq:total>> | Received channel requests.
| chreq:no_channel | <<bsc_chreq:no_channel>> | Sent to MS no channel available.
| handover:attempted | <<bsc_handover:attempted>> | Received handover attempts.
| handover:no_channel | <<bsc_handover:no_channel>> | Sent no channel available responses.
| handover:timeout | <<bsc_handover:timeout>> | Count the amount of timeouts of timer T3103.
| handover:completed | <<bsc_handover:completed>> | Received handover completed.
| handover:failed | <<bsc_handover:failed>> | Receive HO FAIL messages.
| paging:attempted | <<bsc_paging:attempted>> | Paging attempts for a MS.
| paging:detached | <<bsc_paging:detached>> | Counts the amount of paging attempts which couldn't sent out any paging request because no responsible bts found.
| paging:completed | <<bsc_paging:completed>> | Paging successful completed.
| paging:expired | <<bsc_paging:expired>> | Paging Request expired because of timeout T3113.
| chan:rf_fail | <<bsc_chan:rf_fail>> | Received a RF failure indication from BTS.
| chan:rll_err | <<bsc_chan:rll_err>> | Received a RLL failure with T200 cause from BTS.
| bts:oml_fail | <<bsc_bts:oml_fail>> | Received a TEI down on a OML link.
| bts:rsl_fail | <<bsc_bts:rsl_fail>> | Received a TEI down on a OML link.
| bts:codec_amr_f | <<bsc_bts:codec_amr_f>> | Count the usage of AMR/F codec by channel mode requested.
| bts:codec_amr_h | <<bsc_bts:codec_amr_h>> | Count the usage of AMR/H codec by channel mode requested.
| bts:codec_efr | <<bsc_bts:codec_efr>> | Count the usage of EFR codec by channel mode requested.
| bts:codec_fr | <<bsc_bts:codec_fr>> | Count the usage of FR codec by channel mode requested.
| bts:codec_hr | <<bsc_bts:codec_hr>> | Count the usage of HR codec by channel mode requested.
|===
// rate_ctr_group table mobile switching center
.msc - mobile switching center
[options="header"]
|===
| Name | Reference | Description
| loc_update_type:attach | <<msc_loc_update_type:attach>> | Received location update imsi attach requests.
| loc_update_type:normal | <<msc_loc_update_type:normal>> | Received location update normal requests.
| loc_update_type:periodic | <<msc_loc_update_type:periodic>> | Received location update periodic requests.
| loc_update_type:detach | <<msc_loc_update_type:detach>> | Received location update detach indication.
| loc_update_resp:failed | <<msc_loc_update_resp:failed>> | Rejected location updates.
| loc_update_resp:completed | <<msc_loc_update_resp:completed>> | Successful location updates.
| sms:submitted | <<msc_sms:submitted>> | Received a RPDU from a MS (MO).
| sms:no_receiver | <<msc_sms:no_receiver>> | Counts SMS which couldn't routed because no receiver found.
| sms:delivered | <<msc_sms:delivered>> | Global SMS Deliver attempts.
| sms:rp_err_mem | <<msc_sms:rp_err_mem>> | CAUSE_MT_MEM_EXCEEDED errors of MS responses on a sms deliver attempt.
| sms:rp_err_other | <<msc_sms:rp_err_other>> | Other error of MS responses on a sms delive attempt.
| sms:deliver_unknown_error | <<msc_sms:deliver_unknown_error>> | Unknown error occured during sms delivery.
| call:mo_setup | <<msc_call:mo_setup>> | Received setup requests from a MS to init a MO call.
| call:mo_connect_ack | <<msc_call:mo_connect_ack>> | Received a connect ack from MS of a MO call. Call is now succesful connected up.
| call:mt_setup | <<msc_call:mt_setup>> | Sent setup requests to the MS (MT).
| call:mt_connect | <<msc_call:mt_connect>> | Sent a connect to the MS (MT).
| call:active | <<msc_call:active>> | Count total amount of calls that ever reached active state.
| call:complete | <<msc_call:complete>> | Count total amount of calls which got terminated by disconnect req or ind after reaching active state.
| call:incomplete | <<msc_call:incomplete>> | Count total amount of call which got terminated by any other reason after reaching active state.
|===
// generating tables for osmo_stat_items
// generating tables for osmo_counters
// ungrouped osmo_counters
.ungrouped osmo counters
[options="header"]
|===
| Name | Reference | Description
| msc.active_calls | <<ungroup_counter_msc.active_calls>> |
|===

577
doc/manuals/chapters/handover.adoc Normal file
View File

@ -0,0 +1,577 @@
== Handover
Handover is the process of moving a continuously used channel (lchan) from one
cell to another. Usually, that is an ongoing call, so that phones are able to
move across cell coverage areas without interrupting the voice transmission.
A handover can
- stay within one given cell (intra-cell, i.e. simply a new RR Assignment Command);
- occur between two cells that belong to the same BSS (intra-BSC, via RR Handover Command);
- cross BSS boundaries (inter-BSC, via BSSMAP handover procedures);
- move to another MSC (inter-MSC, inter-PLMN);
- move to another RAN type, e.g. from 2G to 3G (inter-RAT, inter-Radio-Access-Technology).
The physical distance is by definition always very near, but handover
negotiation may range from being invisible to the MSC all the way to
orchestrating completely separate RAN stacks.
OsmoBSC currently supports handover within one BSS and between separate BSS.
Whether inter-MSC is supported depends on the MSC implementation (to the BSC,
inter-MSC handover looks identical to inter-BSC handover). Inter-RAT handover
is currently not implemented.
At the time of writing, OsmoMSC's inter-BSC handover support is not complete
yet, so OsmoBSC can perform handover between separate BSS only in conjunction
with a 3rd party MSC implementation.
.Handover support in Osmocom at the time of writing
[cols="^,^,^,^,^"]
|====
| | intra-BSC HO (local BSS) | inter-BSC HO (remote BSS) | inter-MSC HO | inter-RAT HO
| OsmoBSC | rxlev, load-based | rxlev | (planned) | -
| OsmoMSC | (not involved, except for codec changes) | (planned) | (planned) | -
|====
=== How Handover Works
This chapter generally explains handover operations between 2G cells.
==== Internal / Intra-BSC Handover
The BSS is configured to know which cell is physically adjacent to which other
cells, its "neighbors". On the MS/BTS/BSS level, individual cells are
identified by ARFCN+BSIC (frequency + 6-bit identification code).
Each BTS is told by the BSC which cells identified by ARFCN+BSIC are its
adjacent cells. Via System Information, each MS receives a list of these
ARFCN+BSIC, and the MS then return measurements of reception levels.
The BSC is the point of decision whether to do handover or not. This can be a
hugely complex combination of heuristics, knowledge of cell load and codec
capabilites. The most important indicator for handover though is: does an MS
report a neighbor with a better signal than the current cell? See
<<intra_bsc_ho_dot>>.
[[intra_bsc_ho_dot]]
.Intra-BSC Handover stays within the BSS (shows steps only up to activation of the new lchan -- this would be followed by an RR Handover Command, RACH causing Handover Detection, Handover Complete, ...)
[graphviz]
----
include::handover_intra_bsc.dot[]
----
If the BSC sees the need for handover, it will:
- activate a new lchan (with a handover reference ID),
- send an RR Handover Command to the current lchan, and
- wait for the MS to send a Handover RACH to the new lchan ("Handover Detect").
- The RTP stream then is switched over to the new lchan,
- an RSL Establish Indication is expected on the new lchan,
- and the old lchan is released.
Should handover fail at any point, e.g. the new lchan never receives a RACH, or
the MS reports a Handover Failure, then the new lchan is simply released again,
and the old lchan remains in use. If the RTP stream has already been switched
over to the new lchan, it may actually be switched back to the old lchan.
This is simple enough if the new cell is managed by the same BSC: the OsmoMGW
is simply instructed to relay the BTS-side of the RTP stream to another IP
address and port, and the BSC continues to forward DTAP to the MSC
transparently. The operation happens completely within the BSS. If the voice
codec has remained unchanged, the MSC/MNCC may not even be notified that
anything has happened at all.
==== External / Inter-BSC Handover
If the adjacent target cell belongs to a different BSS, the RR procedure for
handover remains the same, but we need to tell the _remote_ BSC to allocate the
new lchan.
The only way to reach the remote BSC is via the MSC, so the MSC must be able
to:
- identify which other BSC we want to talk to,
- forward various BSSMAP Handover messages between old and new BSC,
- redirect the core-side RTP stream to the new BSS at the appropriate time,
- and must finally BSSMAP Clear the connection to the old BSS to conclude the
inter-BSC handover.
[[inter_bsc_ho_dot]]
.Inter-BSC Handover requires the MSC to relay between two BSCs (shows steps only up to the BSSMAP Handover Command -- this would be followed by an RR Handover Command, RACH causing Handover Detection, Handover Complete, ...)
[graphviz]
----
include::handover_inter_bsc.dot[]
----
The first part, identifying the remote BSC, is not as trivial as it sounds: as
mentioned above, on the level of cell information seen by BTS and MS, the
neighbor cells are identified by ARFCN+BSIC. However, on the A-interface and in
the MSC, there is no knowledge of ARFCN+BSIC configurations, and instead each
cell is identified by a LAC and CI (Location Area Code and Cell Identifier).
NOTE: There are several different cell identification types on the A-interface:
from Cell Global Identifier (MCC+MNC+LAC+CI) down to only LAC. OsmoBSC supports
most of these (see <<neighbor_conf_list>>). For simplicity, this description
focuses on LAC+CI identification.
The most obvious reason for using LAC+CI is that identical ARFCN+BSIC are
typically re-used across many cells of the same network operator: an operator
will have only very few ARFCNs available, and the 6bit BSIC opens only a very
limited range of distinction between cells. As long as each cell has no more
than one neighbor per given ARFCN+BSIC, these values can be re-used any number
of times across a network, and even between cells managed by one and the same
BSC.
The consequence of this is that
- the BSC needs to know which remote-BSS cells' ARFCN+BSIC correspond to
exactly which global LAC+CI, and
- the MSC needs to know which LAC+CI are managed by which BSC.
In other words, each BSC requires prior knowledge about the cell configuration
of its remote-BSS neighbor cells, and the MSC requires prior knowledge about
each BSC's cell identifiers; i.e. these config items are spread reduntantly.
=== Configuring Neighbors
The most important step to enable handover in OsmoBSC is to configure each cell
with the ARFCN+BSIC identities of its adjacent neighbors -- both local-BSS and
remote-BSS.
For a long time, OsmoBSC has offered configuration to manually enter the
ARFCN+BSIC sent out as neighbors on various System Information messages (all
`neighbor-list` related commands). This is still possible, however,
particularly for re-using ARFCN+BSIC within one BSS, this method will not work
well.
With the addition of inter-BSC handover support, the new `neighbor` config item
has been added to the `bts` config, to maintain explicit cell-to-cell neighbor
relations, with the possibility to re-use ARFCN+BSIC in each cell.
It is recommended to completely replace `neighbor-list` configurations with the
new `neighbor` configuration described below.
[[neighbor_conf_list]]
.Overview of neighbor configuration on the `bts` config node
[frame="none",grid="none",cols="^10%,^10%,80%"]
|====
| Local | Remote BSS |
| ✓ | | neighbor bts 5
| ✓ | | neighbor lac 200
| ✓ | | neighbor lac-ci 200 3
| ✓ | | neighbor cgi 001 01 200 3
| ✓ | ✓ | neighbor lac 200 arfcn 123 bsic 1
| ✓ | ✓ | neighbor lac-ci 200 3 arfcn 123 bsic 1
| ✓ | ✓ | neighbor cgi 001 01 200 3 arfcn 123 bsic 1
|====
==== Default: All Local Cells are Neighbors
For historical reasons, the default behavior of OsmoBSC is to add all local-BSS cells as neighbors. To
maintain a backwards compatible configuration file format, this is still the case: as soon as no explicit
neighbor cell is configured with a `neighbor` command (either none was configured, or all configured
neighbors have been removed again), a cell automatically lists all of the local-BSS cells as neighbors.
These are implicit mappings in terms of the legacy neighbor configuration scheme, and re-using ARFCN+BSIC
combinations within a BSS will not work well this way.
As soon as the first explicit neighbor relation is added to a cell, the legacy behavior is switched off,
and only explicit neighbors are in effect.
NOTE: If a cell is required to not have any neighbors, it is recommended to rather switch off handover
for that cell with `handover 0`. An alternative solution is to set `neighbor-list mode manual` and not
configure any `neighbor-list` entries.
==== Local-BSS Neighbors
Local neighbors can be configured by just the local BTS number, or by LAC+CI,
or any other supported A-interface type cell identification; also including the
ARFCN+BSIC is optional, it will be derived from the local configuration if
omitted.
OsmoBSC will log errors in case the configuration includes ambiguous ARFCN+BSIC
relations (when one given cell has more than one neighbor for any one
ARFCN+BSIC).
Neighbor relations must be configured explicitly in both directions, i.e. each
cell has to name all of its neighbors, even if the other cell already has an
identical neighbor relation in the reverse direction.
.Example: configuring neighbors within the local BSS in osmo-bsc.cfg, identified by local BTS number
----
network
bts 0
neighbor bts 1
bts 1
neighbor bts 0
----
.Example: configuring neighbors within the local BSS in osmo-bsc.cfg, identified by LAC+CI
----
network
bts 0
# this cell's LAC=23 CI=5
location_area_code 23
cell_identity 5
# reference bts 1
neighbor lac-ci 23 6
bts 1
# this cell's LAC=23 CI=6
location_area_code 23
cell_identity 6
# reference bts 0
neighbor lac-ci 23 5
----
It is allowed to include the ARFCN and BSIC of local neighbor cells, even
though that is redundant with the already known local configuration of the
other cell. The idea is to ease generating the neighbor configuration
automatically, since local-BSS and remote-BSS neighbors then share identical
configuration formatting. For human readability and maintainability, it may
instead be desirable to use the `neighbor bts <0-255>` format.
.Example: configuring neighbors within the local BSS in osmo-bsc.cfg, redundantly identified by LAC+CI as well as ARFCN+BSIC
----
network
bts 0
# this cell's LAC=23 CI=5
location_area_code 23
cell_identity 5
# this cell's ARFCN=1 BSIC=1
trx 0
arfcn 1
base_station_id_code 1
# reference bts 1
neighbor lac-ci 23 6 arfcn 2 bsic 2
bts 1
# LAC=23 CI=6
location_area_code 23
cell_identity 6
# this cell's ARFCN=2 BSIC=2
trx 0
arfcn 2
base_station_id_code 2
# reference bts 0
neighbor lac-ci 23 5 arfcn 1 bsic 1
----
If the cell identification matches a local cell, OsmoBSC will report errors if
the provided ARFCN+BSIC do not match.
==== Remote-BSS Neighbors
Remote-BSS neighbors _always_ need to be configured with full A-interface
identification _and_ ARFCN+BSIC, to allow mapping a cell's neighbor ARFCN+BSIC
to a _BSSMAP Cell Identifier_ (see 3GPP TS 48.008 3.1.5.1 Handover Required
Indication and 3.2.1.9 HANDOVER REQUIRED).
.Example: configuring remote-BSS neighbors in osmo-bsc.cfg, identified by LAC+CI (showing both BSCs' configurations)
----
# BSC Alpha's osmo-bsc.cfg
network
bts 0
# this cell's LAC=23 CI=6
location_area_code 23
cell_identity 6
# this cell's ARFCN=2 BSIC=2
trx 0
arfcn 2
base_station_id_code 2
# fully describe the remote cell by LAC+CI and ARFCN+BSIC
neighbor lac-ci 42 3 arfcn 1 bsic 3
# BSC Beta's osmo-bsc.cfg
network
bts 0
# this cell's LAC=42 CI=3
location_area_code 42
cell_identity 3
# this cell's ARFCN=1 BSIC=3
trx 0
arfcn 1
base_station_id_code 3
# fully describe the remote cell by LAC+CI and ARFCN+BSIC
neighbor lac-ci 23 6 arfcn 2 bsic 2
----
NOTE: It is strongly recommended to stick to a single format for remote-BSS
neighbors' cell identifiers all across an OsmoBSC configuration; i.e. decide
once to use `lac`, `lac-ci` or `cgi` and then stick to that within a given
osmo-bsc.cfg. The reason is that the _Cell Identifier List_ sent in the _BSSMAP
Handover Required_ message must have one single cell identifier type for all
list items. Hence, to be able to send several alternative remote neighbors to
the MSC, the configured cell identifiers must be of the same type. If in doubt,
use the full CGI identifier everywhere.
==== Reconfiguring Neighbors in a Running OsmoBSC
When modifying a cell's neighbor configuration in a telnet VTY session while a cell is already active,
the neighbor configuration will merely be cached in the BSC's local config. To take actual effect, it is
necessary to
- either, re-connect the cell to the BSC (e.g. via `drop bts connection <0-255> oml`)
- or, re-send the System Information using `bts <0-255> resend-system-information`.
=== Configuring Handover Decisions
For a long time, OsmoBSC has supported handover based on reception level
hysteresis (RXLEV) and distance (TA, Timing Advance), known has `algorithm 1`.
Since 2018, OsmoBSC also supports a load-based handover decision algorithm,
known as `algorithm 2`, which also takes cell load, available codecs and
oscillation into consideration. Algorithm 2 had actually been implemented for
the legacy OsmoNITB program many years before the OsmoMSC split, but remained
on a branch, until it was forward-ported to OsmoBSC in 2018.
.What handover decision algorithms take into account
[frame="none",grid="none",cols="^10%,^10%,80%"]
|====
| algorithm 1 | algorithm 2 |
| ✓ | ✓| RXLEV
| ✓ | ✓| RXQUAL
| ✓ | ✓| TA (distance)
| ✓ | ✓| interference (good RXLEV, bad RXQUAL)
| | ✓| load (nr of free lchans, minimum RXLEV and RXQUAL)
| | ✓| penalty time to avoid oscillation
| | ✓| voice rate / codec bias
| ✓ | | inter-BSC: RXLEV hysteresis
| | ✓| inter-BSC: only below minimum RXLEV, RXQUAL
|====
==== Common Configuration
Handover is disabled by default; to disable/enable handover, use `handover
(0|1)`.
Once enabled, algorithm 1 is used by default; choose a handover algorithm with
`handover algorithm (1|2)`:
----
network
# Enable handover
handover 1
# Choose algorithm
handover algorithm 2
# Tweak parameters for algorithm 2 (optional)
handover2 min-free-slots tch/f 4
handover2 penalty-time failed-ho 30
handover2 retries 1
----
All handover algorithms share a common configuration scheme, with an overlay of
three levels:
* immutable compile-time default values,
* configuration on the `network` level for all cells,
* individual cells' configuration on each `bts` node.
Configuration settings relevant for algorithm 1 start with `handover1`, for
algorithm 2 with `handover2`.
The following example overrides the compile-time default for all cells, and
furthermore sets one particular cell on its own individual setting, for the
`min-free-slots tch/f` value:
----
network
handover2 min-free-slots tch/f 4
bts 23
handover2 min-free-slots tch/f 2
----
The order in which these settings are issued makes no difference for the
overlay; i.e., this configuration is perfectly identical to the above, and the
individual cell's value remains in force:
----
network
bts 23
handover2 min-free-slots tch/f 2
handover2 min-free-slots tch/f 4
----
Each setting can be reset to a default value with the `default` keyword. When
resetting an individual cell's value, the globally configured value is used.
When resetting the global value, the compile-time default is used (unless
individual cells still have explicit values configured). For example, this
telnet VTY session removes above configuration first from the cell, then from
the global level:
----
OsmoBSC(config)# network
OsmoBSC(config-net)# bts 23
OsmoBSC(config-net-bts)# handover2 min-free-slots tch/f default
% 'handover2 min-free-slots tch/f' setting removed, now is 4
OsmoBSC(config-net-bts)# exit
OsmoBSC(config-net)# handover2 min-free-slots tch/f default
% 'handover2 min-free-slots tch/f' setting removed, now is 0
----
==== Handover Algorithm 1
Algorithm 1 takes action only when RR Measurement Reports are received from a
BTS. As soon as a neighbor's average RXLEV is higher than the current cell's
average RXLEV plus a hysteresis distance, handover is triggered.
If a handover fails, algorithm 1 will again attempt handover to the same cell
with the next Measurement Report received.
Configuration settings relevant for algorithm 1 start with `handover1`. For
further details, please refer to the OsmoBSC VTY Reference
(<<vty-ref-osmobsc>>) or the telnet VTY online documentation.
==== Handover Algorithm 2
Algorithm 2 is specifically designed to distribute load across cells. A
subscriber will not necessarily remain attached to the cell that has the best
RXLEV average, if that cell is heavily loaded and a less loaded neighbor is
above the minimum allowed RXLEV.
Algorithm 2 also features penalty timers to avoid oscillation: for each
subscriber, if handover to a specific neighbor failed (for a configurable
number of retries), a holdoff timer prevents repeated attempts to handover to
that same neighbor. Several hold-off timeouts following specific situations are
configurable (see `handover2 penalty-time` configuration items).
Configuration settings relevant for algorithm 2 start with `handover2`. For
further details, please refer to the OsmoBSC VTY Reference
<<vty-ref-osmobsc>> or the telnet VTY online documentation.
===== Load Distribution
Load distribution is only supported by algorithm 2.
Load distribution occurs:
- explicitly: every N seconds, OsmoBSC considers all local cells and actively
triggers handover operations to reduce congestion, if any. See
`min-free-slots` below, and the `congestion-check` setting.
- implicitly: when choosing the best neighbor candidate for a handover
triggered otherwise, a congested cell (in terms of `min-free-slots`) is only
used as handover target if there is no alternative that causes less cell
load.
In either case, load distribution will only occur towards neighbor cells that
adhere to minimum reception levels and distance, see `min rxlev` and `max
distance`.
Load distribution will take effect only for already established voice channels.
An MS will always first establish a voice call with its current cell choice; in
load situations, it might be moved to another cell shortly after that.
Considering the best neighbor _before_ starting a new voice call might be
desirable, but is currently not implemented. Consider that RXLEV/RXQUAL ratings
are averaged over a given number of measurement reports, so that the neighbor
ratings may not be valid/reliable yet during early call establishment. In
consequence, it is recommended to ensure a sufficient number of unused logical
channels at all times, though there is no single correct configuration for all
situations.
Most important for load distribution are the `min-free-slots tch/f` and
`min-free-slots tch/h` settings. The default is zero, meaning _no_ load
distribution. To enable, set `min-free-slots` >= 1 for `tch/f` and/or `tch/h`
as appropriate. This setting refers to the minimum number of voice channels
that should ideally remain unused in each individual BTS at all times.
NOTE: it is not harmful to configure `min-free-slots` for a TCH kind that is
not actually present. Such settings will simply be ignored.
NOTE: the number of TCH/F timeslots corresponds 1:1 to the number indicated by
`min-free-slots tch/f`, because each TCH/F physical channel has exactly one
logical channel. In contrast, for each TCH/H timeslot, there are two logical
channels, hence `min-free-slots tch/h` corresponds to twice the number of TCH/H
timeslots configured per cell. In fact, a more accurate naming would have been
"min-free-lchans".
Think of the `min-free-slots` setting as the threshold at which load
distribution is considered. If as many logical channels as required by this
setting are available in a given cell, only changes in RXLEV/RXQUAL/TA trigger
handover away from that cell. As soon as less logical channels remain free, the
periodical congestion check attempts to distribute MS to less loaded neighbor
cells. Every time, the one MS that will suffer the least RXLEV loss while still
reducing congestion will be instructed to move first.
If a cell and its neighbors are all loaded past their `min-free-slots`
settings, the algorithmic aim is equal load: a load-based handover will never
cause the target cell to be more congested than the source cell.
The min-free-slots setting is a tradeoff between immediate voice service
availability and optimal reception levels. A sane choice could be:
- Start off with `min-free-slots` set to half the available logical channels.
- Increase `min-free-slots` if you see MS being rejected too often even though
close neighbors had unused logical channels.
- Decrease `min-free-slots` if you see too many handovers happening for no
apparent reason.
Choosing the optimal setting is not trivial, consider these examples:
- Configure `min-free-slots` = 1: load distribution to other cells will occur
exactly when the last available logical channel has become occupied. The next
time the congestion check runs, at most one handover will occur, so that one
channel is available again. In the intermediate time, all channels will be
occupied, and some MS might be denied immediate voice service because of
that, even though, possibly, other neighbor cells would have provided
excellent reception levels and were completely unloaded. For those MS that
are already in an ongoing voice call and are not physically moving, though,
this almost guarantees service by the closest/best cell.
- Set `min-free-slots` = 2: up to two MS can successfully request voice service
simultaneously (e.g. one MS is establishing a new voice call while another MS
is travelling into this cell). Ideally, two slots have been kept open and are
immediately available. But if a third MS is also traveling into this cell at
the same time, it will not be able to handover into this cell until load
distribution has again taken action to make logical channels available. The
same scenario applies to any arbitrary number of MS asking for voice channels
simultaneously. The operator needs to choose where to draw the line.
- Set `min-free-slots` >= the number of available channels: as soon as any
neighbor is less loaded than a given cell, handover will be attempted. But
imagine there are only two active voice calls on this cell with plenty of
logical channels still unused, and the closest neighbor rates only just above
`min rxlev`; then moving one of the MS _for no good reason_ causes all of:
increased power consumption, reduced reception stability and channel
management overhead.
NOTE: In the presence of dynamic timeslots to provide GPRS service, the number
of voice timeslots left unused also determines the amount of bandwidth
available for GPRS.
==== External / Inter-BSC Handover Considerations
There currently is a profound difference for inter-BSC handover between
algorithm 1 and 2:
For algorithm 1, inter-BSC handover is triggered as soon as the Measurement
Reports and hysteresis indicate a better neighbor than the current cell,
period.
For algorithm 2, a subscriber is "sticky" to the current BSS, and inter-BSC
handover is only even considered when RXLEV/TA drop below minimum requirements.
- If your network topology is such that each OsmoBSC instance manages a single
BTS, and you would like to encourage handover between these, choose handover
algorithm 1. Load balancing will not be available, but RXLEV hysteresis will.
- If your network topology has many cells per BSS, and/or if your BSS
boundaries in tendency correspond to physical/semantic boundaries that favor
handover to remain within a BSS, then choose handover algorithm 2.
The reason for the difference between algorithm 1 and 2 for remote-BSS
handovers is, in summary, the young age of the inter-BSC handover feature in
OsmoBSC:
- So far the mechanisms to communicate cell load to remote-BSS available in the
BSSMAP Handover messages are not implemented, so, a handover due to cell load
across BSS boundaries would be likely to cause handover oscillation between
the two BSS (continuous handover of the same MS back and forth between the
same two cells).
- Algorithm 1 has no `min rxlev` setting.
- Algorithm 1 does not actually use any information besides the Measurement
Reports, and hence can trivially treat all neighbor cells identically.

35
doc/manuals/chapters/handover_inter_bsc.dot Normal file
View File

@ -0,0 +1,35 @@
digraph G {
rankdir=LR
subgraph cluster_bss_a {
label="BSS Alpha"
BTS_a0 [rank=min,label="bts 0\nARFCN=1 BSIC=1\nLAC=23 CI=5"]
BTS_a1 [rank=min,label="bts 1\nARFCN=2 BSIC=2\nLAC=23 CI=6"]
BSC_a [label="BSC Alpha"];
{BTS_a0,BTS_a1} -> BSC_a [arrowhead=none,label=Abis]
}
subgraph cluster_bss_b {
label="BSS Beta"
BTS_b0 [rank=min,label="bts 0\nARFCN=1 BSIC=3\nLAC=42 CI=3"]
BTS_b1 [rank=min,label="bts 1\nARFCN=2 BSIC=4\nLAC=42 CI=1"]
BSC_b [label="BSC Beta"]
{BTS_b0,BTS_b1} -> BSC_b [arrowhead=none,label=Abis]
}
MS -> BTS_a1 [label="(3) Measurement:\nARFCN=1 BSIC=3 RXLEV"]
BTS_a1 -> MS [label="(1) my neighbors:\nARFCN=1 BSIC=1\nARFCN=1 BSIC=3"]
BTS_b0 -> MS [label="(2) good RXLEV",style=dotted]
MS -> {BTS_a0,BTS_b0,BTS_b1} [style=invisible,arrowhead=none]
BTS_a1 -> BSC_a [label="(4) Measurement\nReport",style=dashed]
BTS_a1 -> BTS_b0 [label="(5) BSC decides to do\ninter-BSC Handover",style=dashed,constraint=false]
{BSC_a,BSC_b} -> MSC [arrowhead=none,label=A]
BSC_a -> MSC [label="(6) --> Handover Required\nto LAC=42 CI=6\n(10) <-- Handover Command",style=dashed,constraint=false,arrowhead=none]
MSC -> BSC_b [label="(7) <-- Handover Request\n(9) --> Handover Request ACK",style=dashed,constraint=false,arrowhead=none]
BSC_b -> BTS_b0 [label="(8) activate new lchan",style=dashed,constraint=false]
}

31
doc/manuals/chapters/handover_intra_bsc.dot Normal file
View File

@ -0,0 +1,31 @@
digraph G {
rankdir=LR
subgraph cluster_bss_a {
label="BSS Alpha"
BTS_a0 [rank=min,label="bts 0\nARFCN=1 BSIC=1\nLAC=23 CI=5"]
BTS_a1 [rank=min,label="bts 1\nARFCN=2 BSIC=2\nLAC=23 CI=6"]
BSC_a [label="BSC Alpha"];
{BTS_a0,BTS_a1} -> BSC_a [arrowhead=none,label=Abis]
}
subgraph cluster_bss_b {
label="BSS Beta"
BTS_b0 [rank=min,label="bts 0\nARFCN=1 BSIC=3\nLAC=42 CI=3"]
BTS_b1 [rank=min,label="bts 1\nARFCN=2 BSIC=4\nLAC=42 CI=1"]
BSC_b [label="BSC Beta"]
{BTS_b0,BTS_b1} -> BSC_b [arrowhead=none,label=Abis]
}
MS -> BTS_a1 [label="(3) Measurement:\nARFCN=1 BSIC=1 RXLEV"]
BTS_a1 -> MS [label="(1) my neighbors:\nARFCN=1 BSIC=1\nARFCN=1 BSIC=3"]
BTS_a0 -> MS [label="(2) good RXLEV",style=dotted]
MS -> {BTS_a0,BTS_b0,BTS_b1} [style=invisible,arrowhead=none]
BTS_a1 -> BSC_a [label="(4) Measurement\nReport",style=dashed]
BTS_a1 -> BTS_a0 [label="(5) BSC decides to do\nintra-BSC Handover",style=dashed,constraint=false]
BSC_a -> BTS_a0 [label="(6) activate new lchan",style=dashed,constraint=false]
{BSC_a,BSC_b} -> MSC [arrowhead=none,label=A]
}

174
doc/manuals/chapters/overview.adoc Normal file
View File

@ -0,0 +1,174 @@
[[overview]]
== Overview
This manual should help you getting started with OsmoBSC. It will cover
aspects of configuring and running the OsmoBSC.
[[intro_overview]]
=== About OsmoBSC
OsmoBSC is the Osmocom implementation of a Base Station Controller. It
implements:
- an 'A-bis' interface towards BTSs and
- an 'A' interface towards an MSC. It is important to be aware that there are
two variants of the 'A' interface, see <<a-interface>>.
=== Software Components
OsmoBSC contains a variety of different software components, which
we'll briefly describe in this section.
==== A-bis Implementation
OsmoBSC implements the ETSI/3GPP specified A-bis interface, including TS 08.56
(LAPD), TS 08.58 (RSL) and TS 12.21 (OML). In addition, it supports a variety
of vendor-specific extensions and dialects in order to communicate with BTSs
from Siemens, Nokia, Ericsson, ip.access, Octasic and sysmocom, as well as
various USRP based BTS implementations, using OsmoBTS and OsmoTRX (like the
Ettus B200 series, the Fairwaves XTRX or the LimeSDR, to name a few).
For more information, see <<bts>> and <<bts-examples>>.
[[a-interface]]
==== A Implementation
OsmoBSC implements a sub-set of the GSM A interface as specified in TS 08.08
(BSSAP) and TS 04.08 (DTAP).
Osmocom offers two variants of the 'A' interface's protocol stacking:
- 'A/SCCPlite'
- 'A/SCCP/M3UA'
Traditionally, OsmoBSC only implemented the A/SCCPlite protocol, but since a
proper M3UA implementation is available from 'libosmo-sigtran'
('libosmo-sccp.git'), the stock OsmoBSC now supports only A/SCCP/M3UA. (The
idea is that SCCPlite support may be added to libosmo-sigtran at some point
in the future, after which the new `osmo-bsc` would support both variants of
the A interface.)
The difference between an A/SCCPlite and A/SCCP/M3UA is illustrated in
<<fig-sccplite>> and <<fig-sccp-m3ua>>.
===== A/SCCPlite
Unlike classic A interface implementations for E1 interfacs,
`osmo-bsc-sccplite` implements a variant of encapsulating the A interface over
IP. To do so, the SCCP messages are wrapped in an IPA multiplex and then
communicated over TCP. The audio channels are mapped to RTP streams.
This protocol stacking is sometimes called "SCCPlite".
At the time of writing, if you would like to use the old A/SCCPlite protocol,
look for binary packages named `osmo-bsc-sccplite`, or compile `osmo-bsc` from
the 'openbsc.git' repository.
[[fig-sccplite]]
.`osmo-bsc-sccplite` operation using 'A/SCCPlite'
[graphviz]
----
digraph G {
rankdir=LR;
MS0 [label="MS"];
MS1 [label="MS"];
MS2 [label="MS"];
MS3 [label="MS"];
BTS0 [label="BTS"];
BTS1 [label="BTS"];
BSC [label="OsmoBSC-SCCPlite"];
MSC [label="3rd party MSC"];
{MS0,MS1}->BTS0 [label="Um"];
{MS2,MS3}->BTS1 [label="Um"];
{BTS0,BTS1}->BSC [label="Abis\nTCP\nIP"];
BSC->MSC [label="A\nSCCP\nTCP\nIP"];
}
----
===== A/SCCP/M3UA
The default OsmoBSC's A interface uses the M3UA variant of SIGTRAN protocol
stacking:
|=====
|A
|SCCP
|M3UA
|SCTP
|IP
|=====
To use the now-default A/SCCP/M3UA protocol, look for binary packages named
`osmo-bsc`, or compile `osmo-bsc` from the 'osmo-bsc.git' repository. It is
recommended to use the M3UA variant, which is required to operate with OsmoMSC.
To route SCCP/M3UA messages between OsmoBSC and and MSC, an STP instance like
OsmoSTP is required.
[[fig-sccp-m3ua]]
.`osmo-bsc` operation using 'A/SCCP/M3UA'
[graphviz]
----
digraph G {
rankdir=LR;
MS0 [label="MS"];
MS1 [label="MS"];
MS2 [label="MS"];
MS3 [label="MS"];
BTS0 [label="BTS"];
BTS1 [label="BTS"];
BSC [label="OsmoBSC"];
STP [label="OsmoSTP"];
MSC [label="OsmoMSC\n(or 3rd-party MSC)"];
{MS0,MS1}->BTS0 [label="Um"];
{MS2,MS3}->BTS1 [label="Um"];
{BTS0,BTS1}->BSC [label="Abis\nTCP\nIP"];
BSC->STP->MSC [label="A\nSCCP\nM3UA\nSCTP\nIP"];
}
----
==== BSC Implementation
The BSC implementation covers the classic functionality of a GSM Base
Station Controller, i.e.
* configuring and bringing up BTSs with their TRXs and TSs
* implementing the A-bis interface / protocols for signalling and actual
voice data (TRAU frames).
* processing measurement results from the mobile stations in dedicated
mode, performing hand-over decision and execution.
* Terminating the TS 04.08 RR (Radio Resource) sub-layer from the MS.
For more information, see <<net>>, <<bts>> and <<bts-examples>>.
==== TRAU mapper / E1 sub-channel muxer
Unlike classic GSM networks, OsmoBSC does not perform any transcoding.
Rather, a compatible codec is selected for both legs of a call, and
codec frames are passed through transparently. In order to achieve this
with E1 based BTS, OsmoBSC contains a E1 sub-channel de- and
re-multiplexer as well as a TRAU mapper that can map uplink to downlink
frames and vice versa.
=== Control interface
The actual protocol is described in <<common-control-if>> section. Here we
describe variables specific to OsmoBSC.
.Variables available over control interface
[options="header",width="100%",cols="20%,5%,5%,50%,20%"]
|===
|Name|Access|Trap|Value|Comment
|msc_connection_status|RO|Yes|"connected", "disconnected"|Indicate the status of connection to MSC.
|bts_connection_status|RO|Yes|"connected", "disconnected"|Indicate the status of connection to BTS.
|location|RW|Yes|"<unixtime>,(invalid\|fix2d\|fix3d),<lat>,<lon>,<height>"|Set/Get location data.
|timezone|RW|No|"<hours>,<mins>,<dst>", "off"|-19 <= hours <= 19, mins in {0, 15, 30, 45}, and 0 <= dst <= 2
|notification|WO|Yes||
|inform-msc-v1|WO|Yes||
|ussd-notify-v1|WO|Yes||
|===
Some comments.
FIXME: commands defined in src/ctrl/control_if.c? Nodes? Traps?

42
doc/manuals/chapters/running.adoc Normal file
View File

@ -0,0 +1,42 @@
== Running OsmoBSC
The OsmoBSC executable (`osmo-bsc`) offers the following command-line
arguments:
=== SYNOPSIS
*osmo-bsc* [-h|-V] [-d 'DBGMASK'] [-D] [-c 'CONFIGFILE'] [-s] [-T] [-e 'LOGLEVEL'] [-l 'IP'] [-r 'RFCTL']
=== OPTIONS
*-h, --help*::
Print a short help message about the supported options
*-V, --version*::
Print the compile-time version number of the OsmoBTS program
*-d, --debug 'DBGMASK','DBGLEVELS'*::
Set the log subsystems and levels for logging to stderr. This
has mostly been superseded by VTY-based logging configuration,
see <<logging>> for further information.
*-D, --daemonize*::
Fork the process as a daemon into background.
*-c, --config-file 'CONFIGFILE'*::
Specify the file and path name of the configuration file to be
used. If none is specified, use `osmo-bsc.cfg` in the current
working directory.
*-s, --disable-color*::
Disable colors for logging to stderr. This has mostly been
deprecated by VTY based logging configuration, see <<logging>>
for more information.
*-T, --timestamp*::
Enable time-stamping of log messages to stderr. This has mostly
been deprecated by VTY based logging configu- ration, see
<<logging>> for more information.
*-e, --log-level 'LOGLEVEL'*::
Set the global log level for logging to stderr. This has mostly
been deprecated by VTY based logging configuration, see
<<logging>> for more information.
*-l, --local='IP'*::
Specify the local IP address of the OsmoBSC-MGCP
*-r, --rf-ctl 'RFCTL'*::
Offer a Unix domain socket for RF control at the path/filename
'RFCTL' in the file system.

146
doc/manuals/message-sequences/mo_call-abis_a.msc Normal file
View File

@ -0,0 +1,146 @@
msc {
hscale=2;
ms [label="MS"],
bts [label="BTS"],
bsc_l [label="BSC(lchan SDCCH)"],
bsc_l2 [label="BSC(lchan TCH)"],
bsc [label="BSC"],
mgw [label="MGW@BSC"],
m_sc [label="MSC"];
...;
--- [label="MS Requests dedicated channel"];
ms -> bts [label="RACH: REQ"];
bts -> bsc [label="RSL Cchan CHAN RQD"];
bsc_l <= bsc [label="allocate lchan (RR IMM ASS)", textcolor="red", linecolor="red"];
bts <- bsc_l [label="RSL Dchan (SDCCH) CHAN ACT"];
bts -> bsc_l [label="RSL Dchan (SDCCH) CHAN ACT ACK"];
bts <- bsc_l [label="RSL Cchan IMM ASS (RR IMM ASS)"];
bsc_l box bsc_l [label="Start T3101"];
ms <- bts [label="AGCH: RR IMM ASS"];
--- [label="MS Establishes SDCCH"];
ms -> bts [label="SDCCH: SABM (CM SERV REQ)"];
ms <- bts [label="SDCCH: UA (CM SERV REQ)"];
bts -> bsc_l [label="RSL RLL (SDCCH, SAPI0, DCCH) EST IND", textcolor="green", linecolor="green"];
bsc_l box bsc_l [label="Stop T3101"];
bsc_l => bsc [label="GSCON_EV_A_CONN_REQ", textcolor="red", linecolor="red"];
bsc -> m_sc [label="SCCP CR (BSSMAP COMPL L3 (CM SERV REQ))"];
bsc <- m_sc [label="SCCP CC"];
bsc -> bsc [label="GSCON_EV_A_CONN_CFM", textcolor="red", linecolor="red"];
ms box m_sc [label="Authentication, MM info, ..."];
bsc <- m_sc [label="SCCP DT1 (DTAP (CM SERV ACK)"];
bsc -> bsc [label="GSCON_EV_MT_DTAP", textcolor="red", linecolor="red"];
bsc_l <= bsc [label="lchan_submit_dtap(CM SERV ACK)", textcolor="red", linecolor="red"];
bts <- bsc_l [label="RSL RLL (SDCCH) DATA REQ (CM SERV ACK)", textcolor="green", linecolor="green"];
ms <- bts [label="SDCCH: I (CM SERV ACK)"];
ms -> bts [label="SDCCH: I (CC SETUP)"];
bts -> bsc_l [label="RSL RLL (SDCCH) DATA IND (CC SETUP)", textcolor="green", linecolor="green"];
bsc_l -> bsc [label="GSCON_EV_MO_DTAP", textcolor="red", linecolor="red"];
bsc -> m_sc [label="SCCP DT1 (DTAP (CC SETUP))"];
...;
--- [label="MSC assigns Voice Channel (TCH)"];
bsc <- m_sc [label="SCCP DT1 (BSSMAP ASSIGNMENT CMD)"];
bsc -> bsc [label="GSCON_EV_A_ASSIGNMENT_CMD", textcolor="red", linecolor="red"];
bsc_l2 <= bsc [label="allocate lchan", textcolor="red", linecolor="red"];
bts <- bsc_l2 [label="RSL Dchan (TCH) CHAN ACT"];
bts -> bsc_l2 [label="RSL Dchan (TCH) CHAN ACT ACK"];
bts <- bsc_l [label="RSL RLL (SDDCH) DATA REQ (RR ASSIGNMENT CMD)", textcolor="green",
linecolor="green"];
bsc_l2 box bsc_l2 [label="Start T3107"];
ms <- bts [label="SDCCH: I (RR ASSIGNMENT CMD)"];
ms box ms [label="local-end RLL release", textcolor="green", linecolor="green"];
bts -> bsc_l [label="RSL RLL (SDCCH) REL IND", textcolor="gray", linecolor="green"];
bsc_l => bsc [label="GSCON_EV_RLL_REL_IND", textcolor="gray", linecolor="red"];
bts -> bsc_l [label="RSL Dchan (SDCCH) CONN FAIL IND", textcolor="gray", linecolor="green"];
bsc_l => bsc [label="GSCON_EV_CONN_FAIL", textcolor="gray", linecolor="red"];
bsc_l box bsc_l [label="BSC must ignore failures on old channel"];
ms -> bts [label="TCH: SABM (RR ASSIGNMENT CMPL)"];
ms <- bts [label="TCH: UA (RR ASSIGNMENT CMPL)"];
bts -> bsc_l2 [label="RSL RLL (TCH, SAPI0, DCCH) EST IND", textcolor="green", linecolor="green"];
bsc_l2 box bsc_l2 [label="Stop T3107"];
bsc_l2 => bsc [label="GSCON_EV_RR_ASS_COMPL", textcolor="red", linecolor="red"];
bsc_l <= bsc [label="release_lchan(SDCCH)", textcolor="red", linecolor="red"];
bts box bsc_l [label="local-end RLL release", textcolor="green", linecolor="green"];
bts <- bsc_l [label="RSL Dchan (SDCCH) RF CHAN REL"];
bts <- bsc_l [label="RSL RLL (SDCCH, SAPI0, DCCH) REL REQ", textcolor="gray", linecolor="green"];
bts <- bsc_l [label="RSL DChan (SDCCH) DEACTIVATE SACCH", textcolor="gray", linecolor="black"];
bts -> bsc_l [label="RSL RLL (SDCCH, SAPI0, DCCH) RF FAIL IND", textcolor="gray", linecolor="green"];
bts -> bsc_l [label="RSL Dchan (SDCCH, SAPI0, DCCH) RF CHAN REL ACK"];
# connect BTS RTP with BSC-MGW RTP
--- [label="BSC configures RTP on BTS and both sides of MGW"];
bts <- bsc [label="RSL IPA CRCX", textcolor="blue", linecolor="blue"];
bts box bts [label="Bind to BTS-local RTP Port (1000)", textcolor="blue", linecolor="blue"];
bts -> bsc [label="IPA CRCX ACK (BTS:1000)", textcolor="blue", linecolor="blue"];
bsc -> mgw [label="MGCP CRCX rtpbridge/2@mgw (BTS:1000)", textcolor="blue", linecolor="blue"];
mgw box mgw [label="Bind to MGW-local RTP Port (2000)\nConnect to BTS:1000", textcolor="blue", linecolor="blue"];
bsc <- mgw [label="MGCP CRCX rtpbridge/2@mgw OK (MGW:2000)", textcolor="blue", linecolor="blue"];
bts <- bsc [label="IPA MDCX (MGW:2000)", textcolor="blue", linecolor="blue"];
bts box bts [label="Connect RTP socket to remote (MGW) RTP Port", textcolor="blue", linecolor="blue"];
bts -> bsc [label="IPA MDCX ACK", textcolor="blue", linecolor="blue"];
bsc >> mgw [label="MGCP MDCX rtpbridge/2@mgw", textcolor="gray", linecolor="gray"];
bsc << mgw [label="MGCP MDCX rtpbridge/2@mgw OK", textcolor="gray", linecolor="gray"];
...;
--- [label="BSC finally can report successful TCH assignment"];
bsc -> m_sc [label="SCCP DT1 (BSSMAP ASSGN CMPL (3GPP AoIP MGW:3000))"];
m_sc box m_sc [label="Connect remote RTP to MGW addr from ASSGN CMPL"];
...;
mgw <-> m_sc [label="RTP Audio MGW:3000 MSC:4000", textcolor="blue", linecolor="blue"];
bts <-> mgw [label="RTP Audio BTS:1000 MGW:2000", textcolor="blue", linecolor="blue"];
ms <-> bts [label="Um Audio (bidirectional)", textcolor="blue", linecolor="blue"];
ms <-> m_sc [label="DTAP CC ALERTING"];
...;
--- [label="Further signalling in parallel with RTP (simplified)"];
ms <- m_sc [label="DTAP CC CONNECT"];
ms -> m_sc [label="DTAP CC CONNECT ACK"];
--- [label="Voice Call in Progress"];
...;
--- [label="B-end hangs up"];
ms <- m_sc [label="DTAP CC DISCONNET"];
ms <- m_sc [label="DTAP CC RELEASE"];
ms <- m_sc [label="DTAP CC RELEASE COMPL"];
...;
bsc <- m_sc [label="SCCP DT1 (BSSMAP CLEAR CMD)"];
bsc -> bsc [label="GSCON_EV_A_CLEAR_CMD", textcolor="red", linecolor="red"];
--- [label="BSC must release terrestrial resoures before reporting CLEAR COMPLETE"];
mgw <- bsc [label="MGCP DLCX rtpbridge/2@mgw", textcolor="blue", linecolor="blue"];
mgw box mgw [label="Release MSC-facing local RTP port (3000)", textcolor="blue", linecolor="blue"];
mgw -> bsc [label="MGCP DLCX rtpbridge/2@mgw OK", textcolor="blue", linecolor="blue"];
mgw <- bsc [label="MGCP DLCX rtpbridge/2@mgw", textcolor="blue", linecolor="blue"];
mgw box mgw [label="Release BTS-facing local RTP port (2000)", textcolor="blue", linecolor="blue"];
mgw -> bsc [label="MGCP DLCX rtpbridge/2@mgw OK", textcolor="blue", linecolor="blue"];
bts <- bsc [label="IPA DLCX", textcolor="blue", linecolor="blue"];
bts box bts [label="Release BTS-local RTP port (1000)", textcolor="blue", linecolor="blue"];
bts -> bsc [label="IPA DLCX OK", textcolor="blue", linecolor="blue"];
bsc -> bsc [label="GSCON_EV_RSL_CLEAR_COMPL", textcolor="red", linecolor="red"];
bsc -> m_sc [label="SCCP DT1 (BSSMAP CLEAR COMPL)"];
bsc <- m_sc [label="SCCP RLSD"];
bsc -> bsc [label="GSCON_EV_A_DISC_IND", textcolor="red", linecolor="red"];
bsc -> m_sc [label="SCCP RLC"];
--- [label="BSC releases radio resources after CLEAR COMPLETE"];
bsc_l2 <= bsc [label="release_lchan(TCH)", textcolor="red", linecolor="red"];
bts <- bsc_l2 [label="RSL RLL (TCH, SAPI0, DCCH) DATA REQ (RR CHANNEL RELEASE)", textcolor="green", linecolor="green"];
bsc_l2 box bsc_l2 [label="Start T3109"];
bts <- bsc_l2 [label="RSL Dchan (TCH) DEACTIVATE SACCH"];
ms <- bts [label="TCH: I (RR CHANNEL RELEASE)"];
ms -> bts [label="TCH: DISC (RR CHANNEL RELEASE)"];
bts -> bsc_l2 [label="RSL RLL (TCH, SAPI0, DCCH) REL IND", textcolor="green", linecolor="green"];
bsc_l2 => bsc [label="GSCON_EV_RLL_REL_IND", textcolor="red", linecolor="red"];
bsc_l2 box bsc_l2 [label="Stop T3109; Start T3111"];
# optional: Conn Fail?
bts <- bsc_l2 [label="RSL Dchan (TCH, SAPI0, DCCH) RF CHAN REL"];
bts -> bsc_l2 [label="RSL Dchan (TCH, SAPI0, DCCH) RF CHAN REL ACK"];
bsc_l2 box bsc_l2 [label="T3111 timeout: Channel can be used again"];
...;
}

39
doc/manuals/mgw/classic-bsc.msc Normal file
View File

@ -0,0 +1,39 @@
# MO Call on a classic E1 Abis BTS with classic E1 A BSC
# not actually supported by OsmoBSC (nor planned), for refrence only
msc {
hscale=2;
ms [label="MS"], bts [label="E1 BTS"], bsc[label="OsmoBSC"], trau[label="TRAU"], m_sc[label="MSC"];
ms box m_sc [label="We assume a SDCCH is already established"];
...;
ms -> m_sc [label="DTAP CC SETUP"];
ms <- m_sc [label="DTAP CC CALL PROCEEDING"];
bsc <- m_sc [label="BSSAP ASSGN REQ"];
bsc box m_sc [label="E1 TS for PCM specified by CIC"];
bts <- bsc [label="RSL CHAN ACT"];
bts -> bsc [label="RSL CHAN ACT ACK"];
bts box bsc [label="E1 TS + 16k sub-slot configured for given lchan"];
ms <-> bsc [label="Assignment"];
bsc -> m_sc [label="BSSAP ASSGN CMPL"];
...;
trau <- m_sc [label="PCM Audio in full E1 slot"];
bts <- trau [label="A-bis TRAU frames on 16k sub-slot"];
...;
ms <- m_sc [label="DTAP CC CONNECT"];
ms -> m_sc [label="DTAP CC CONNECT ACK"];
trau <-> m_sc [label="PCM Audio in full E1 slot"];
bts <-> trau [label="A-bis TRAU frames on 16k sub-slot"];
--- [label="Voice Call in Progress"];
ms <- m_sc [label="DTAP CC DISCONNET"];
ms <- m_sc [label="DTAP CC RELEASE"];
ms <- m_sc [label="DTAP CC RELEASE COMPL"];
...;
bsc <- m_sc [label="BSSMAP CLEAR CMD"];
bsc -> m_sc [label="BSSMAP CLEAR COMPL"];
bsc <- m_sc [label="SCCP RLSD"];
bsc -> m_sc [label="SCCP RLC"];
}

50
doc/manuals/mgw/osmo-bsc-new-mgw-e1.msc Normal file
View File

@ -0,0 +1,50 @@
# MO-Call with E1 BTS + OsmoBSC with true 3GPP AoIP (planned
# osmo-bsc_mgcp has to be extended to true MGW functionality!
msc {
hscale=2;
ms [label="MS"], bts [label="E1 BTS"], bsc[label="OsmoBSC"], mgcp[label="osmo-bsc_mgcp"], m_sc[label="MSC"];
ms box m_sc [label="We assume a SDCCH is already established"];
...;
ms -> m_sc [label="DTAP CC SETUP"];
ms <- m_sc [label="DTAP CC CALL PROCEEDING"];
m_sc box m_sc [label="Bind arbitrary local port (4000)"];
bsc <- m_sc [label="BSSAP ASSGN REQ (3GPP AoIP MSC:4000)"];
bts <- bsc [label="RSL CHAN ACT"];
bts -> bsc [label="RSL CHAN ACT ACK"];
ms <-> bsc [label="Assignment"];
...;
mgcp <- bsc [label="MGCP CRCX ts1/ss2@mgw (MSC:4000)"];
mgcp box mgcp [label="Bind to MGW-local RTP Port (3000)\nConnect to MSC:4000"];
mgcp -> bsc [label="MGCP CRCX ts1/ss2@mgw OK (MGW:3000)"];
...;
bsc -> m_sc [label="BSSAP ASSGN CMPL (3GPP AoIP MGW:3000)"];
m_sc box m_sc [label="Connect remote RTP to MGW addr from ASSGN CMPL"];
...;
mgcp <=> m_sc [label="RTP Audio MGW:3000 MSC:4000"];
bts <=> mgcp [label="TRAU Frame Audio (E1 TS1 SS2)"];
ms <=> bts [label="Um Audio (bidirectional)"];
ms <-> m_sc [label="DTAP CC ALERTING"];
...;
ms <- m_sc [label="DTAP CC CONNECT"];
ms -> m_sc [label="DTAP CC CONNECT ACK"];
--- [label="Voice Call in Progress"];
ms <- m_sc [label="DTAP CC DISCONNET"];
ms <- m_sc [label="DTAP CC RELEASE"];
ms <- m_sc [label="DTAP CC RELEASE COMPL"];
...;
bsc <- m_sc [label="BSSMAP CLEAR CMD"];
bsc -> m_sc [label="BSSMAP CLEAR COMPL"];
bsc <- m_sc [label="SCCP RLSD"];
bsc -> m_sc [label="SCCP RLC"];
...;
mgcp <- bsc [label="MGCP DLCX ts1/ss2@mgw"];
mgcp box mgcp [label="Release MSC-facing local RTP port (3000)"];
mgcp -> bsc [label="MGCP DLCX ts1/ss2@mgw OK"];
}

71
doc/manuals/mgw/osmo-bsc-new-mgw.msc Normal file
View File

@ -0,0 +1,71 @@
# MO-Call with OsmoBTS + OsmoBSC with true 3GPP AoIP (planned)
msc {
hscale=2;
ms [label="MS"], bts [label="OsmoBTS"], bsc[label="OsmoBSC"], mgcp[label="osmo-bsc_mgcp"], m_sc[label="MSC"];
ms box m_sc [label="We assume a SDCCH is already established"];
...;
ms -> m_sc [label="DTAP CC SETUP"];
ms <- m_sc [label="DTAP CC CALL PROCEEDING"];
m_sc box m_sc [label="Bind arbitrary local port (4000)"];
bsc <- m_sc [label="BSSAP ASSGN REQ (3GPP AoIP MSC:4000)"];
bts <- bsc [label="RSL CHAN ACT"];
bts -> bsc [label="RSL CHAN ACT ACK"];
ms <-> bsc [label="Assignment"];
...;
# connect BTS RTP with BSC-MGW RTP
bts <- bsc [label="IPA CRCX"];
bts box bts [label="Bind to BTS-local RTP Port (1000)"];
bts -> bsc [label="IPA CRCX ACK (BTS:1000)"];
bsc -> mgcp [label="MGCP CRCX rtpbridge/2@mgw (BTS:1000)"];
mgcp box mgcp [label="Bind to MGW-local RTP Port (2000)\nConnect to BTS:1000"];
bsc <- mgcp [label="MGCP CRCX rtpbridge/2@mgw OK (MGW:2000)"];
bts <- bsc [label="IPA MDCX (MGW:2000)"];
bts box bts [label="Connect RTP socket to remote (MGW) RTP Port"];
bts -> bsc [label="IPA MDCX ACK"];
#bsc -> mgcp [label="MGCP MDCX rtpbridge/2@mgw (optional)"];
#bsc <- mgcp [label="MGCP MDCX rtpbridge/2@mgw OK (optional)"];
...;
mgcp <- bsc [label="MGCP CRCX rtpbridge/2@mgw (MSC:4000)"];
mgcp box mgcp [label="Bind to MGW-local RTP Port (3000)\nConnect to MSC:4000"];
mgcp -> bsc [label="MGCP CRCX rtpbridge/2@mgw OK (MGW:3000)"];
...;
bsc -> m_sc [label="BSSAP ASSGN CMPL (3GPP AoIP MGW:3000)"];
m_sc box m_sc [label="Connect remote RTP to MGW addr from ASSGN CMPL"];
...;
mgcp <=> m_sc [label="RTP Audio MGW:3000 MSC:4000"];
bts <=> mgcp [label="RTP Audio BTS:1000 MGW:2000"];
ms <=> bts [label="Um Audio (bidirectional)"];
ms <-> m_sc [label="DTAP CC ALERTING"];
...;
ms <- m_sc [label="DTAP CC CONNECT"];
ms -> m_sc [label="DTAP CC CONNECT ACK"];
--- [label="Voice Call in Progress"];
ms <- m_sc [label="DTAP CC DISCONNET"];
ms <- m_sc [label="DTAP CC RELEASE"];
ms <- m_sc [label="DTAP CC RELEASE COMPL"];
...;
bsc <- m_sc [label="BSSMAP CLEAR CMD"];
bsc -> m_sc [label="BSSMAP CLEAR COMPL"];
bsc <- m_sc [label="SCCP RLSD"];
bsc -> m_sc [label="SCCP RLC"];
...;
mgcp <- bsc [label="MGCP DLCX rtpbridge/2@mgw"];
mgcp box mgcp [label="Release MSC-facing local RTP port (3000)"];
mgcp -> bsc [label="MGCP DLCX rtpbridge/2@mgw OK"];
mgcp <- bsc [label="MGCP DLCX rtpbridge/2@mgw"];
mgcp box mgcp [label="Release BTS-facing local RTP port (2000)"];
mgcp -> bsc [label="MGCP DLCX rtpbridge/2@mgw OK"];
bts <- bsc [label="IPA DLCX"];
bts box bts [label="Release BTS-local RTP port (1000)"];
bts -> bsc [label="IPA DLCX OK"];
}

64
doc/manuals/mgw/osmo-bsc-old-sccplite.msc Normal file
View File

@ -0,0 +1,64 @@
# MO-Call with OsmoBTS + OsmoBSC using A/IP with IPA/SCCPlite
# Supported since 2010 using osmo-bsc + osmo-bsc_nat
msc {
hscale=2;
ms [label="MS"], bts [label="OsmoBTS"], bsc[label="OsmoBSC"], mgcp[label="osmo-bsc_mgcp"], m_sc[label="MSC"];
ms box m_sc [label="We assume a SDCCH is already established"];
...;
ms -> m_sc [label="DTAP CC SETUP"];
ms <- m_sc [label="DTAP CC CALL PROCEEDING"];
bsc <- m_sc [label="BSSAP ASSGN REQ"];
bts <- bsc [label="RSL CHAN ACT"];
bts -> bsc [label="RSL CHAN ACT ACK"];
ms <-> bsc [label="Assignment"];
bsc -> m_sc [label="BSSAP ASSGN CMPL"];
...;
bts <- bsc [label="IPA CRCX"];
bts box bts [label="Bind to BSC-local RTP Port"];
bts -> bsc [label="IPA CRCX ACK"];
bts <- bsc [label="IPA MDCX"];
bts box bts [label="Connect RTP socket to remote (bsc_mgcp) RTP Port"];
bts -> bsc [label="IPA MDCX ACK"];
mgcp <- m_sc [label="MGCP CRCX 1@mgw"];
mgcp box mgcp [label="Bind to BTS-local RTP Port"];
mgcp -> m_sc [label="MGCP CRCX 1@mgw OK"];
mgcp <- m_sc [label="MGCP MDCX 1@mgw (recvonly) "];
mgcp box mgcp [label="Connect RTP socket to remote (MSC) RTP Port"];
mgcp -> m_sc [label="MGCP MDCX 1@mgw OK"];
mgcp <= m_sc [label="RTP Audio"];
bts <= mgcp [label="RTP Audio"];
ms <= bts [label="Um Audio (unidirectional)"];
ms <- m_sc [label="DTAP CC ALERTING"];
...;
mgcp <- m_sc [label="MGCP MDCX (sndrecv) "];
mgcp box mgcp [label="Switch to bi-directional audio"];
mgcp -> m_sc [label="MGCP MDCX OK"];
mgcp <=> m_sc [label="RTP Audio"];
bts <=> mgcp [label="RTP Audio"];
ms <=> bts [label="Um Audio (bidirectional)"];
...;
ms <- m_sc [label="DTAP CC CONNECT"];
ms -> m_sc [label="DTAP CC CONNECT ACK"];
mgcp <- m_sc [label="MGCP MDCX 1@mgw (sndrecv) "];
mgcp box mgcp [label="Why?"];
mgcp -> m_sc [label="MGCP MDCX 1@mgw OK"];
--- [label="Voice Call in Progress"];
ms <- m_sc [label="DTAP CC DISCONNET"];
ms <- m_sc [label="DTAP CC RELEASE"];
ms <- m_sc [label="DTAP CC RELEASE COMPL"];
...;
bsc <- m_sc [label="BSSMAP CLEAR CMD"];
bsc -> m_sc [label="BSSMAP CLEAR COMPL"];
bsc <- m_sc [label="SCCP RLSD"];
bsc -> m_sc [label="SCCP RLC"];
...;
mgcp <- m_sc [label="MGCP DLCX 1@mgw"];
mgcp box mgcp [label="Release local RTP port"];
mgcp -> m_sc [label="MGCP DLCX 1@mgw OK"];
}

2
doc/manuals/om2000/README Normal file
View File

@ -0,0 +1,2 @@
This is a set of message sequence charts documneting our understanding
of Ericsson OM2000 at BTS start-up, by looking at protocol traces.

24
doc/manuals/om2000/om2k-bts.msc Normal file
View File

@ -0,0 +1,24 @@
msc {
trxc [label="TRXC"], tf [label="TF"], is [label="IS"], cf [label="CF"], bsc [label="BSC"];
cf => bsc [label="Fault Report"];
cf <=> bsc [label="Start incl. Negotiation"];
cf <=> bsc [label="Operational Info"];
is <=> bsc [label="Connect"];
is <=> bsc [label="Reset"];
is <=> bsc [label="Start"];
is <=> bsc [label="Config"];
is <=> bsc [label="Enable"];
is <=> bsc [label="Operational Info"];
trxc <=> bsc [label="TRXC + dependent objects"];
cf <=> bsc [label="Calendar Time"];
tf <=> bsc [label="Connect"];
tf <=> bsc [label="Reset"];
tf <=> bsc [label="Start"];
tf <=> bsc [label="Config"];
tf <=> bsc [label="Enable"];
tf <=> bsc [label="Operational Info"];
}

19
doc/manuals/om2000/om2k-mo-cf.msc Normal file
View File

@ -0,0 +1,19 @@
msc {
bts [label="BTS (CF)"], bsc [label="BSC"];
# this is for the Central Function Object
--- [label="Initial state after initializing OML TEI"];
bts <= bsc [label="Start Request"];
bts => bsc [label="Reset Request Accept"];
bts => bsc [label="Negotiation Request"];
bts <= bsc [label="Negotiation Request ACK"];
bts => bsc [label="Start Result (Started)"];
bts <= bsc [label="Start Result ACK"];
bts <= bsc [label="Operational Info (Operational)"];
bts => bsc [label="Operational Info Accept"];
# continue with IS, TRXC, TF
}

29
doc/manuals/om2000/om2k-mo-is.msc Normal file
View File

@ -0,0 +1,29 @@
msc {
bts [label="BTS (IS)"], bsc [label="BSC"];
# this is for the Interface Switch Object
--- [label="Initial state after initializing CF"];
bts <= bsc [label="Connect Command"];
bts => bsc [label="Connect Complete"];
bts <= bsc [label="Reset Command"];
bts => bsc [label="Reset Complete"];
bts <= bsc [label="Start Request"];
bts => bsc [label="Start Request Accept"];
bts => bsc [label="Start Result (Disabled)"];
bts <= bsc [label="Start Result ACK"];
bts <= bsc [label="IS Configuration Request"];
bts => bsc [label="IS Configuration Request Accept"];
bts => bsc [label="IS Configuration Result (According to Req)"];
bts <= bsc [label="IS Configuration Result ACK"];
bts <= bsc [label="Enable Request"];
bts => bsc [label="Enable Request Accept"];
bts => bsc [label="Enable Result (Enabled)"];
bts <= bsc [label="Enable Result ACK"];
bts <= bsc [label="Operational Info (Operational)"];
bts => bsc [label="Operational Info Accept"];
}

31
doc/manuals/om2000/om2k-mo-rx.msc Normal file
View File

@ -0,0 +1,31 @@
msc {
bts [label="TRX (RX)"], bsc [label="BSC"];
# this is for the TRX Receiver Object
--- [label="Initial state after initializing TRXC"];
bts <= bsc [label="Connect Command"];
bts => bsc [label="Connect Complete"];
bts <= bsc [label="Reset Command"];
bts => bsc [label="Reset Complete"];
bts <= bsc [label="Start Request"];
bts => bsc [label="Start Request Accept"];
bts => bsc [label="Start Result (Disabled)"];
bts <= bsc [label="Start Result ACK"];
bts <= bsc [label="Start Request"];
bts => bsc [label="Reset Request Accept"];
bts => bsc [label="Start Result (Disabled)"];
bts <= bsc [label="Start Result ACK"];
bts <= bsc [label="RX Configuration Request"];
bts => bsc [label="RX Configuration Request Accept"];
bts => bsc [label="RX Configuration Result"];
bts <= bsc [label="RX Configuration Result ACK"];
bts <= bsc [label="Enable Request"];
bts => bsc [label="Enable Request Accept"];
bts => bsc [label="Enable Result (Enabled)"];
bts <= bsc [label="Enable Result ACK"];
}

29
doc/manuals/om2000/om2k-mo-tf.msc Normal file
View File

@ -0,0 +1,29 @@
msc {
bts [label="BTS (TF)"], bsc [label="BSC"];
# this is for the Timing Funcition Object
--- [label="Initial state after initializing CF"];
bts <= bsc [label="Connect Command"];
bts => bsc [label="Connect Complete"];
bts <= bsc [label="Reset Command"];
bts => bsc [label="Reset Complete"];
bts <= bsc [label="Start Request"];
bts => bsc [label="Reset Request Accept"];
bts => bsc [label="Start Result (Disabled)"];
bts <= bsc [label="Start Result ACK"];
bts <= bsc [label="TF Configuration Request"];
bts => bsc [label="TF Configuration Request Accept"];
bts => bsc [label="TF Configuration Result (According to Req)"];
bts <= bsc [label="TF Configuration Result ACK"];
bts <= bsc [label="Enable Request"];
bts => bsc [label="Enable Request Accept"];
bts => bsc [label="Enable Result (Enabled)"];
bts <= bsc [label="Enable Result ACK"];
bts <= bsc [label="Operational Info (Operational)"];
bts => bsc [label="Operational Info Accept"];
}

16
doc/manuals/om2000/om2k-mo-trxc.msc Normal file
View File

@ -0,0 +1,16 @@
msc {
bts [label="TRX (TRXC)"], bsc [label="BSC"];
# this is for the TRX Controller Object
--- [label="Initial state after initializing IS"];
bts <= bsc [label="Reset Command"];
bts => bsc [label="Reset Complete"];
bts <= bsc [label="Start Request"];
bts => bsc [label="Reset Request Accept"];
bts => bsc [label="Start Result (Started)"];
bts <= bsc [label="Start Result ACK"];
bts <= bsc [label="Operational Info (Operational)"];
bts => bsc [label="Operational Info Accept"];
}

28
doc/manuals/om2000/om2k-mo-ts.msc Normal file
View File

@ -0,0 +1,28 @@
msc {
bts [label="TRX (TS)"], bsc [label="BSC"];
# this is for the Timeslot Object
--- [label="Initial state after initializing RX"];
bts <= bsc [label="Connect Command"];
bts => bsc [label="Connect Complete"];
bts <= bsc [label="Reset Command"];
bts => bsc [label="Reset Complete"];
bts <= bsc [label="Start Request"];
bts => bsc [label="Reset Request Accept"];
bts => bsc [label="Start Result (Disabled)"];
bts <= bsc [label="Start Result ACK"];
bts <= bsc [label="TS Configuration Request"];
bts => bsc [label="TS Configuration Request Accept"];
bts => bsc [label="TS Configuration Result"];
bts <= bsc [label="TS Configuration Result ACK"];
bts <= bsc [label="Enable Request"];
bts => bsc [label="Enable Request Accept"];
bts => bsc [label="Enable Result (Enabled)"];
bts <= bsc [label="Enable Result ACK"];
# continue with BCCH filling after all TS
}

26
doc/manuals/om2000/om2k-mo-tx.msc Normal file
View File

@ -0,0 +1,26 @@
msc {
bts [label="TRX (TX)"], bsc [label="BSC"];
# this is for the TRX Transmitter Object
--- [label="Initial state after initializing TRXC"];
bts <= bsc [label="Connect Command"];
bts => bsc [label="Connect Complete"];
bts <= bsc [label="Reset Command"];
bts => bsc [label="Reset Complete"];
bts <= bsc [label="Start Request"];
bts => bsc [label="Reset Request Accept"];
bts => bsc [label="Start Result (Disabled)"];
bts <= bsc [label="Start Result ACK"];
bts <= bsc [label="TX Configuration Request"];
bts => bsc [label="TX Configuration Request Accept"];
bts => bsc [label="TX Configuration Result"];
bts <= bsc [label="TX Configuration Result ACK"];
bts <= bsc [label="Enable Request"];
bts => bsc [label="Enable Request Accept"];
bts => bsc [label="Enable Result (Enabled)"];
bts <= bsc [label="Enable Result ACK"];
}

33
doc/manuals/om2000/om2k-trx.msc Normal file
View File

@ -0,0 +1,33 @@
msc {
hscale=2;
ts [label="TS"], rx [label="RX"], tx [label="TX"], trxc [label="TRXC"], bsc [label="BSC"];
trxc => bsc [label="Fault Report"];
trxc <=> bsc [label="Reset"];
trxc <=> bsc [label="Start"];
trxc <=> bsc [label="Operational Info"];
--- [label="Do we wait for TF here?"];
tx <=> bsc [label="Connect"];
tx <=> bsc [label="Reset"];
tx <=> bsc [label="Start"];
tx <=> bsc [label="Config"];
tx <=> bsc [label="Enable"];
rx <=> bsc [label="Connect"];
rx <=> bsc [label="Reset"];
rx <=> bsc [label="Start"];
rx <=> bsc [label="Config"];
rx <=> bsc [label="Enable"];
ts <=> bsc [label="Connect"];
ts <=> bsc [label="Reset"];
ts <=> bsc [label="Start"];
ts <=> bsc [label="Config"];
ts <=> bsc [label="Enable"];
trxc <=> bsc [label="BCCH INFO"];
trxc <=> bsc [label="Other RSL procedures"];
}

78
doc/manuals/osmobsc-usermanual-docinfo.xml Normal file
View File

@ -0,0 +1,78 @@
<revhistory>
<revision>
<revnumber>1</revnumber>
<date>February 2016</date>
<authorinitials>HW</authorinitials>
<revremark>
Initial OsmoBSC manual, recycling OsmoNITB sections
</revremark>
</revision>
<revision>
<revnumber>2</revnumber>
<date>October 2018</date>
<authorinitials>NH</authorinitials>
<revremark>
Add Handover chapter: document new neighbor configuration, HO algorithm 2
and inter-BSC handover.
</revremark>
</revision>
</revhistory>
<authorgroup>
<author>
<firstname>Holger</firstname>
<surname>Freyther</surname>
<email>hfreyther@sysmocom.de</email>
<authorinitials>HF</authorinitials>
<affiliation>
<shortaffil>sysmocom</shortaffil>
<orgname>sysmocom - s.f.m.c. GmbH</orgname>
<jobtitle>former Managing Director</jobtitle>
</affiliation>
</author>
<author>
<firstname>Harald</firstname>
<surname>Welte</surname>
<email>hwelte@sysmocom.de</email>
<authorinitials>HW</authorinitials>
<affiliation>
<shortaffil>sysmocom</shortaffil>
<orgname>sysmocom - s.f.m.c. GmbH</orgname>
<jobtitle>Managing Director</jobtitle>
</affiliation>
</author>
<author>
<firstname>Neels</firstname>
<surname>Hofmeyr</surname>
<email>nhofmeyr@sysmocom.de</email>
<authorinitials>NH</authorinitials>
<affiliation>
<shortaffil>sysmocom</shortaffil>
<orgname>sysmocom - s.f.m.c. GmbH</orgname>
<jobtitle>Developer</jobtitle>
</affiliation>
</author>
</authorgroup>
<copyright>
<year>2012-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 the Invariant Sections being just 'Foreword',
'Acknowledgements' and 'Preface', with 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>

43
doc/manuals/osmobsc-usermanual.adoc Normal file
View File

@ -0,0 +1,43 @@
:gfdl-enabled:
OsmoBSC User Manual
===================
Harald Welte <hwelte@sysmocom.de>
include::../common/chapters/preface.adoc[]
include::chapters/overview.adoc[]
include::chapters/running.adoc[]
include::chapters/control.adoc[]
include::chapters/counters.adoc[]
include::chapters/handover.adoc[]
include::../common/chapters/vty.adoc[]
include::../common/chapters/logging.adoc[]
include::../common/chapters/bts.adoc[]
include::{srcdir}/chapters/bts-examples.adoc[]
include::../common/chapters/bsc.adoc[]
include::../common/chapters/abis.adoc[]
include::../common/chapters/control_if.adoc[]
include::../common/chapters/cell-broadcast.adoc[]
include::../common/chapters/port_numbers.adoc[]
include::../common/chapters/bibliography.adoc[]
include::../common/chapters/glossary.adoc[]
include::../common/chapters/gfdl.adoc[]

44
doc/manuals/osmobsc-vty-reference.xml Normal file
View File

@ -0,0 +1,44 @@
<?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 XML 5.0//EN"
"http://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>13th August 2012</date>
<authorinitials>hf</authorinitials>
<revremark>Initial</revremark>
</revision>
<revision>
<revnumber>v2</revnumber>
<date>5th March 2014</date>
<authorinitials>hf</authorinitials>
<revremark>Update to match osmo-bsc version 0.13.0-305</revremark>
</revision>
</revhistory>
<title>OsmoBSC VTY Reference</title>
<copyright>
<year>2012-2014</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>

97
doc/manuals/osmux-reference-docinfo.xml Normal file
View File

@ -0,0 +1,97 @@
<revhistory>
<revision>
<revnumber>0.1</revnumber>
<date>11 June 2012</date>
<authorinitials>Pablo Neira Ayuso</authorinitials>
<revremark>
Initial version of the proposal for internal discussion.
</revremark>
</revision>
<revision>
<revnumber>0.2</revnumber>
<date>11 June 2012</date>
<authorinitials>Pablo Neira Ayuso</authorinitials>
<revremark>
Second version after comments from Holger and Harald:
Include figures that provide expect traffic savings (in %).
Change licensing terms (owned by OnWaves and consultants).
Adjust work from 200 to 150 hours, remove details on how the implementation
</revremark>
</revision>
<revision>
<revnumber>0.3</revnumber>
<date>20 June 2017</date>
<authorinitials>Pau Espin Pedrol</authorinitials>
<revremark>
Improve and extenend for osmo-gsm-manuals inclusion from Pau Espin:
Convert to asciidoc.
Update frame bits according to implementation.
</revremark>
</revision>
<revision>
<revnumber>0.4</revnumber>
<date>19 July 2017</date>
<authorinitials>Pau Espin Pedrol</authorinitials>
<revremark>
Add sequence charts, generate packet header structure with packetdiag, generate traffic saving plot with pychart.
</revremark>
</revision>
</revhistory>
<authorgroup>
<author>
<firstname>Holger</firstname>
<surname>Freyther</surname>
<email>hfreyther@sysmocom.de</email>
<authorinitials>HF</authorinitials>
<affiliation>
<shortaffil>sysmocom</shortaffil>
<orgname>sysmocom - s.f.m.c. GmbH</orgname>
<jobtitle>former Managing Director</jobtitle>
</affiliation>
</author>
<author>
<firstname>Harald</firstname>
<surname>Welte</surname>
<email>hwelte@sysmocom.de</email>
<authorinitials>HW</authorinitials>
<affiliation>
<shortaffil>sysmocom</shortaffil>
<orgname>sysmocom - s.f.m.c. GmbH</orgname>
<jobtitle>Managing Director</jobtitle>
</affiliation>
</author>
<author>
<firstname>Pablo</firstname>
<surname>Neira Ayuso</surname>
<email>pneira@sysmocom.de</email>
<authorinitials>PN</authorinitials>
<affiliation>
<shortaffil>sysmocom</shortaffil>
<orgname>sysmocom - s.f.m.c. GmbH</orgname>
</affiliation>
</author>
</authorgroup>
<copyright>
<year>2012-2017</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 the Invariant Sections being just 'Foreword',
'Acknowledgements' and 'Preface', with 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>

592
doc/manuals/osmux-reference.adoc Normal file
View File

@ -0,0 +1,592 @@
[[osmux]]
= OSmux: reduce of SAT uplink costs by protocol optimizations
== Problem
In case of satellite based GSM systems, the transmission cost on the back-haul
is relatively expensive. The billing for such SAT uplink is usually done in a
pay-per-byte basis. Thus, reducing the amount of bytes transfered would
significantly reduce the cost of such uplinks. In such environment, even
seemingly small protocol optimizations, eg. message batching and trunking, can
result in significant cost reduction.
This is true not only for speech codec frames, but also for the constant
background load caused by the signalling link (A protocol). Optimizations in
this protocol are applicable to both VSAT back-haul (best-effort background IP)
as well as Inmarsat based links (QoS with guaranteed bandwidth).
== Proposed solution
In order to reduce the bandwidth consumption, this document proposes to develop
a multiplex protocol that will be used to proxy voice and signalling traffic
through the SAT links.
=== Voice
For the voice case, we propose a protocol that provides:
* Batching: that consists of putting multiple codec frames on the sender side
into one single packet to reduce the protocol header overhead. This batch
is then sent as one RTP/UDP/IP packet at the same time. Currently, AMR 5.9
codec frames are transported in a RTP/UDP/IP protocol stacking. This means
there are 15 bytes of speech codec frame, plus a 2 byte RTP payload header,
plus the RTP (12 bytes), UDP (8 bytes) and IP (20 bytes) overhead. This means
we have 40 byte overhead for 17 byte payload.
* Trunking: in case of multiple concurrent voice calls, each of them will
generate one speech codec frame every 20ms. Instead of sending only codec
frames of one voice call in a given IP packet, we can 'interleave' or trunk
the codec frames of multiple calls into one IP. This further increases the
IP packet size and thus improves the payload/overhead ratio.
Both techniques should be applied without noticeable impact in terms of user
experience. As the satellite back-haul has very high round trip time (several
hundred milliseconds), adding some more delay is not going to make things
significantly worse.
For the batching, the idea consists of batching multiple codec frames on the
sender side, A batching factor (B) of '4' means that we will send 4 codec
frames in one underlying protocol packet. The additional delay of the batching
can be computed as (B-1)*20ms as 20ms is the duration of one codec frame.
Existing experimentation has shown that a batching factor of 4 to 8 (causing a
delay of 60ms to 140ms) is acceptable and does not cause significant quality
degradation.
The main requirements for such voice RTP proxy are:
* Always batch codec frames of multiple simultaneous calls into single UDP
message.
* Batch configurable number codec frames of the same call into one UDP
message.
* Make sure to properly reconstruct timing at receiver (non-bursty but
one codec frame every 20ms).
* Implementation in libosmo-netif to make sure it can be used
in osmo-bts (towards osmo-bsc), osmo-bsc (towards osmo-bts and
osmo-bsc_nat) and osmo-bsc_nat (towards osmo-bsc)
* Primary application will be with osmo-bsc connected via satellite link to
osmo-bsc_nat.
* Make sure to properly deal with SID (silence detection) frames in case
of DTX.
* Make sure to transmit and properly re-construct the M (marker) bit of
the RTP header, as it is used in AMR.
* Primary use case for AMR codec, probably not worth to waste extra
payload byte on indicating codec type (amr/hr/fr/efr). If we can add
the codec type somewhere without growing the packet, we'll do it.
Otherwise, we'll skip this.
=== Signalling
Signalling uses SCCP/IPA/TCP/IP stacking. Considering SCCP as payload, this
adds 3 (IPA) + 20 (TCP) + 20 (IP) = 43 bytes overhead for every signalling
message, plus of course the 40-byte-sized TCP ACK sent in the opposite
direction.
While trying to look for alternatives, we consider that none of the standard IP
layer 4 protocols are suitable for this application. We detail the reasons
why:
* TCP is a streaming protocol aimed at maximizing the throughput of a stream
withing the constraints of the underlying transport layer. This feature is
not really required for the low-bandwidth and low-pps GSM signalling.
Moreover, TCP is stream oriented and does not conserve message boundaries.
As such, the IPA header has to serve as a boundary between messages in the
stream. Moreover, assuming a generally quite idle signalling link, the
assumption of a pure TCP ACK (without any data segment) is very likely to
happen.
* Raw IP or UDP as alternative is not a real option, as it does not recover
lost packets.
* SCTP preserves message boundaries and allows for multiple streams
(multiplexing) within one connection, but it has too much overhead.
For that reason, we propose the use of LAPD for this task. This protocol was
originally specified to be used on top of E1 links for the A interface, who
do not expose any kind of noticeable latency. LAPD resolves (albeit not as
good as TCP does) packet loss and copes with packet re-ordering.
LAPD has a very small header (3-5 octets) compared to TCPs 20 bytes. Even if
LAPD is put inside UDP, the combination of 11 to 13 octets still saves a
noticable number of bytes per packet. Moreover, LAPD has been modified for less
reliable interfaces such as the GSM Um interface (LAPDm), as well as for the
use in satellite systems (LAPsat in ETSI GMR).
== OSmux protocol
The OSmux protocol is the core of our proposed solution. This protocol operates
over UDP or, alternatively, over raw IP. The designated default UDP port number
and IP protocol type have not been yet decided.
Every OSmux message starts with a control octet. The control octet contains a
2-bit Field Type (FT) and its location starts on the 2nd bit for backward
compatibility with older versions (used to be 3 bits). The FT defines the
structure of the remaining header as well as the payload.
The following FT values are assigned:
* FT == 0: LAPD Signalling
* FT == 1: AMR Codec
* FT == 2: Dummy
* FT == 3: Reserved for Fture Use
There can be any number of OSmux messages batched up in one underlaying packet.
In this case, the multiple OSmux messages are simply concatenated, i.e. the
OSmux header control octet directly follows the last octet of the payload of the
previous OSmux message.
=== LAPD Signalling (0)
[packetdiag]
----
{
colwidth = 32
node_height = 40
0: -
1-2: FT
3-7: ----
8-15: PL-LENGTH
16-31: LAPD header + payload
}
----
Field Type (FT): 2 bits::
The Field Type allocated for LAPD Signalling frames is "0".
This frame type is not yet supported inside OsmoCom and may be subject to
change in future versions of the protocol.
=== AMR Codec (1)
This OSmux packet header is used to transport one or more RTP-AMR packets for a
specific RTP stream identified by the Circuit ID field.
[packetdiag]
----
{
colwidth = 32
node_height = 40
0: M
1-2: FT
3-5: CTR
6: F
7: Q
8-15: Red. TS/SeqNR
16-23: Circuit ID
24-27: AMR FT
28-31: AMR CMR
}
----
Marker (M): 1 bit::
This is a 1:1 mapping from the RTP Marker (M) bit as specified in RFC3550
Section 5.1 (RTP) as well as RFC3267 Section 4.1 (RTP-AMR). In AMR, the Marker
is used to indicate the beginning of a talk-spurt, i.e. the end of a silence
period. In case more than one AMR frame from the specific stream is batched into
this OSmux header, it is guaranteed that the first AMR frame is the first in the
talkspurt.
Field Type (FT): 2 bits::
The Field Type allocated for AMR Codec frames is "1".
Frame Counter (CTR): 2 bits::
Provides the number of batched AMR payloads (starting 0) after the header. For
instance, if there are 2 AMR payloads batched, CTR will be "1".
AMR-F (F): 1 bit::
This is a 1:1 mapping from the AMR F field in RFC3267 Section 4.3.2. In case
there are multiple AMR codec frames with different F bit batched together, we
only use the last F and ignore any previous F.
AMR-Q (Q): 1 bit::
This is a 1:1 mapping from the AMR Q field (Frame quality indicator) in RFC3267
Section 4.3.2. In case there are multiple AMR codec frames with different Q bit
batched together, we only use the last Q and ignore any previous Q.
Circuit ID Code (CIC): 8 bits::
Identifies the Circuit (Voice call), which in RTP is identified by {srcip,
srcport, dstip, dstport, ssrc}.
Reduced/Combined Timestamp and Sequence Number (RCTS): 8 bits::
Resembles a combination of the RTP timestamp and sequence number. In the GSM
system, speech codec frames are generated at a rate of 20ms. Thus, there is no
need to have independent timestamp and sequence numbers (related to a 8kHz
clock) as specified in AMR-RTP.
AMR Codec Mode Request (AMR-FT): 4 bits::
This is a mapping from te AMR FT field (Frame type index) in RFC3267 Section
4.3.2. The length of each codec frame needs to be determined from this field. It
is thus guaranteed that all frames for a specific stream in an OSmux batch are
of the same AMR type.
AMR Codec Mode Request (AMR-CMR): 4 bits::
The RTP AMR payload header as specified in RFC3267 contains a 4-bit CMR field.
Rather than transporting it in a separate octet, we squeeze it in the lower four
bits of the clast octet. In case there are multiple AMR codec frames with
different CMR, we only use the last CMR and ignore any previous CMR.
==== Additional considerations
* It can be assumed that all OSmux frames of type AMR Codec contain at least 1
AMR frame.
* Given a batch factor of N frames (N>1), it can not be assumed that the amount
of AMR frames in any OSmux frame will always be N, due to some restrictions
mentioned above. For instance, a sender can decide to send before queueing the
expected N frames due to timing issues, or to conform with the restriction
that the first AMR frame in the batch must be the first in the talkspurt
(Marker M bit).
=== Dummy (2)
This kind of frame is used for NAT traversal. If a peer is behind a NAT, its
source port specified in SDP will be a private port not accessible from the
outside. Before other peers are able to send any packet to it, they require the
mapping between the private and the public port to be set by the firewall,
otherwise the firewall will most probably drop the incoming messages or send it
to a wrong destination. The firewall in most cases won't create a mapping until
the peer behind the NAT sends a packet to the peer residing outside.
In this scenario, if the peer behind the nat is expecting to receive but never
transmit audio, no packets will ever reach him. To solve this, the peer sends
dummy packets to let the firewall create the port mapping. When the other peers
receive this dummy packet, they can infer the relation between the original
private port and the public port and start sending packets to it.
When opening a connection, the peer is expected to send dummy packets until it
starts sending real audio, at which point dummy packets are not needed anymore.
[packetdiag]
----
{
colwidth = 32
node_height = 40
0: -
1-2: FT
3-5: CTR
6-7: --
8-15: ----
16-23: Circuit ID
24-27: AMR FT
28-31: ----
}
----
Field Type (FT): 2 bits::
The Field Type allocated for Dummy frames is "2".
Frame Counter (CTR): 2 bits::
Provides the number of dummy batched AMR payloads (starting 0) after the header.
For instance, if there are 2 AMR payloads batched, CTR will be "1".
Circuit ID Code (CIC): 8 bits::
Identifies the Circuit (Voice call), which in RTP is identified by {srcip,
srcport, dstip, dstport, ssrc}.
AMR Codec Mode Request (AMR-FT): 4 bits::
This field must contain any valid value described in the AMR FT field (Frame
type index) in RFC3267 Section 4.3.2.
==== Additional considerations
* After the header, additional padding needs to be allocated to conform with CTR
and AMR FT fields. For instance, if CTR is 0 and AMR FT is AMR 6.9, a padding
of 17 bytes is to be allocated after the header.
* On receival of this kind of OSmux frame, it's usually enough for the reader to
discard the header plus the calculated padding and keep operating.
== Sequence Charts
=== Trunking
Following chart shows how trunking works for 3 concurrent calls from different
MS on a given BTS. In this case only uplink data is shown, but downlink follows
the same idea. Batching factor is set to 1 to easily illustrate trunking mechanism.
It can be seen how 3 RTP packets from 3 different Ms (a, b, and c) arrive to the
BSC from the BTS. The BSC generates 3 OSmux frames and stores and sends them
together in one UDP packet to the BSC-NAT. The BSC-NAT decodes the three OSmux
frames, identifies each of them through CID values and transform them back to
RTP before sending them to the MGW.
["mscgen"]
----
msc {
hscale = 2;
bts [label="BTS"], bsc [label="BSC"], bscnat [label="BSC-NAT"], mgw [label="MGW"];
...;
--- [label="3 Regular RTP-AMR calls using OSmux (has been ongoing for some time)"];
bts => bsc [label="RTP-AMR[seq=y,ssrc=MSa]"];
bts => bsc [label="RTP-AMR[seq=x,ssrc=MSb]"];
bts => bsc [label="RTP-AMR[seq=z,ssrc=MSc]"];
bsc => bscnat [label="UDP[Osmux[ft=2,cid=i,seq=m,AMR(y)],Osmux[ft=2,cid=i+1,seq=n,AMR(x)],Osmux[ft=2,cid=i+2,seq=l,AMR(z)]]"];
bscnat => mgw [label="RTP-AMR[seq=o,ssrc=r] (originally seq=y,ssrc=MSa)"];
bscnat => mgw [label="RTP-AMR[seq=p,ssrc=s] (originally seq=x,ssrc=MSb)"];
bscnat => mgw [label="RTP-AMR[seq=q,ssrc=t] (originally seq=z,ssrc=MSc)"];
bts => bsc [label="RTP-AMR[seq=y+1,ssrc=MSa]"];
bts => bsc [label="RTP-AMR[seq=x+1,ssrc=MSb]"];
bts => bsc [label="RTP-AMR[seq=z+1,ssrc=MSc]"];
bsc => bscnat [label="UDP[Osmux[ft=2,cid=i,seq=m+1,AMR(y+1)],Osmux[ft=2,cid=i+1,seq=n+1,AMR(x+1)],Osmux[ft=2,cid=i+2,seq=l+1,AMR(z+1)]]"];
bscnat => mgw [label="RTP-AMR[seq=o+1,ssrc=r] (originally seq=y+1,ssrc=MSa)"];
bscnat => mgw [label="RTP-AMR[seq=p+1,ssrc=s] (originally seq=x+1,ssrc=MSb)"];
bscnat => mgw [label="RTP-AMR[seq=q+1,ssrc=t] (originally seq=z+1,ssrc=MSc)"];
bts => bsc [label="RTP-AMR[seq=y+2,ssrc=MSa]"];
bts => bsc [label="RTP-AMR[seq=x+2,ssrc=MSb]"];
bts => bsc [label="RTP-AMR[seq=z+2,ssrc=MSc]"];
bsc => bscnat [label="UDP[Osmux[ft=2,cid=i,seq=m+2,AMR(y+2)],Osmux[ft=2,cid=i+1,seq=n+2,AMR(x+2)],Osmux[ft=2,cid=i+2,seq=l+2,AMR(z+2)]]"];
bscnat => mgw [label="RTP-AMR[seq=o+2,ssrc=r] (originally seq=y+2,ssrc=MSa)"];
bscnat => mgw [label="RTP-AMR[seq=p+2,ssrc=s] (originally seq=x+2,ssrc=MSb)"];
bscnat => mgw [label="RTP-AMR[seq=q+2,ssrc=t] (originally seq=z+2,ssrc=MSc)"];
}
----
=== Batching
Following chart shows how batching with a factor of 3 works. To easilly
illustrate batching, only uplink and one concurrent call is considered.
It can be seen how 3 RTP packets from MSa arrive to the BSC from the BTS. The
BSC queues the 3 RTP packets and once the batchfactor is reached, an OSmux frame
is generated and sent to the BSC-NAT. The BSC-NAT decodes the OSmux frames,
transforms each AMR payload into an RTP packet and each RTP packet is scheduled
for delivery according to expected proportional time delay (and timestamp field
is set accordingly).
["mscgen"]
----
msc {
hscale = 2;
bts [label="BTS"], bsc [label="BSC"], bscnat [label="BSC-NAT"], mgw [label="MGW"];
...;
--- [label="Regular RTP-AMR call using OSmux with batch factor 3 (has been ongoing for some time)"];
bts => bsc [label="RTP-AMR[seq=x,ssrc=MSa]"];
bts => bsc [label="RTP-AMR[seq=x+1,ssrc=MSa]"];
bts => bsc [label="RTP-AMR[seq=x+2,ssrc=MSa]"];
bsc => bscnat [label="UDP[Osmux[ft=2,cid=i,seq=m,AMR(x),AMR(x+1),AMR(x+2)]]"];
bscnat => mgw [label="RTP-AMR[seq=o,ssrc=r] (originally seq=x,ssrc=MSa)"];
bscnat => mgw [label="RTP-AMR[seq=o+1,ssrc=r] (originally seq=x+1,ssrc=MSa)"];
bscnat => mgw [label="RTP-AMR[seq=o+2,ssrc=r] (originally seq=x+2,ssrc=MSa)"];
bts => bsc [label="RTP-AMR[seq=x+3,ssrc=MSa]"];
bts => bsc [label="RTP-AMR[seq=x+4,ssrc=MSa]"];
bts => bsc [label="RTP-AMR[seq=x+5,ssrc=MSa]"];
bsc => bscnat [label="UDP[Osmux[ft=2,cid=i,seq=m+1,AMR(x+3),AMR(x+4),AMR(x+5)]]"];
bscnat => mgw [label="RTP-AMR[seq=o+3,ssrc=r] (originally seq=x+3,ssrc=MSa)"];
bscnat => mgw [label="RTP-AMR[seq=o+4,ssrc=r] (originally seq=x+4,ssrc=MSa)"];
bscnat => mgw [label="RTP-AMR[seq=o+5,ssrc=r] (originally seq=x+5,ssrc=MSa)"];
bts => bsc [label="RTP-AMR[seq=x+6,ssrc=MSa]"];
bts => bsc [label="RTP-AMR[seq=x+7,ssrc=MSa]"];
bts => bsc [label="RTP-AMR[seq=x+8,ssrc=MSa]"];
bsc => bscnat [label="UDP[Osmux[ft=2,cid=i,seq=m+2,AMR(x+6),AMR(x+7),AMR(x+8)]]"];
bscnat => mgw [label="RTP-AMR[seq=o+6,ssrc=r] (originally seq=x+6,ssrc=MSa)"];
bscnat => mgw [label="RTP-AMR[seq=o+7,ssrc=r] (originally seq=x+7,ssrc=MSa)"];
bscnat => mgw [label="RTP-AMR[seq=o+8,ssrc=r] (originally seq=x+8,ssrc=MSa)"];
}
----
=== Trunking and Batching
Following chart shows how trunking and batching work together. The chart shows 2
concurrent calls from different MS on a given BTS, and BSC is configured with a
batch factor of 3. Again only uplink data is shown, but downlink follows the
same idea. Batching factor is set to 1 to easily illustrate trunking mechanism.
["mscgen"]
----
msc {
hscale = 2;
bts [label="BTS"], bsc [label="BSC"], bscnat [label="BSC-NAT"], mgw [label="MGW"];
...;
--- [label="2 Regular RTP-AMR call using OSmux with batch factor 3 (has been ongoing for some time)"];
bts => bsc [label="RTP-AMR[seq=x,ssrc=MSa]"];
bts => bsc [label="RTP-AMR[seq=y,ssrc=MSb]"];
bts => bsc [label="RTP-AMR[seq=x+1,ssrc=MSa]"];
bts => bsc [label="RTP-AMR[seq=y+1,ssrc=MSb]"];
bts => bsc [label="RTP-AMR[seq=x+2,ssrc=MSa]"];
bts => bsc [label="RTP-AMR[seq=y+2,ssrc=MSb]"];
bsc => bscnat [label="UDP[Osmux[ft=2,cid=i,seq=m,AMR(x),AMR(x+1),AMR(x+2)],Osmux[ft=2,cid=i+1,seq=n,AMR(y),AMR(y+1),AMR(y+2)]]"];
bscnat => mgw [label="RTP-AMR[seq=o,ssrc=r] (originally seq=x,ssrc=MSa)"];
bscnat => mgw [label="RTP-AMR[seq=p,ssrc=s] (originally seq=y,ssrc=MSb)"];
bscnat => mgw [label="RTP-AMR[seq=o+1,ssrc=r] (originally seq=x+1,ssrc=MSa)"];
bscnat => mgw [label="RTP-AMR[seq=p+1,ssrc=s] (originally seq=y+1,ssrc=MSb)"];
bscnat => mgw [label="RTP-AMR[seq=o+2,ssrc=r] (originally seq=x+2,ssrc=MSa)"];
bscnat => mgw [label="RTP-AMR[seq=p+2,ssrc=s] (originally seq=y+2,ssrc=MSb)"];
bts => bsc [label="RTP-AMR[seq=x+3,ssrc=MSa]"];
bts => bsc [label="RTP-AMR[seq=y+3,ssrc=MSb]"];
bts => bsc [label="RTP-AMR[seq=x+4,ssrc=MSa]"];
bts => bsc [label="RTP-AMR[seq=y+4,ssrc=MSb]"];
bts => bsc [label="RTP-AMR[seq=x+5,ssrc=MSa]"];
bts => bsc [label="RTP-AMR[seq=y+5,ssrc=MSb]"];
bsc => bscnat [label="UDP[Osmux[ft=2,cid=i,seq=m+1,AMR(x+3),AMR(x+4),AMR(x+5)],Osmux[ft=2,cid=i+1,seq=n+1,AMR(y+3),AMR(y+4),AMR(y+5)]]"];
bscnat => mgw [label="RTP-AMR[seq=o+3,ssrc=r] (originally seq=x+3,ssrc=MSa)"];
bscnat => mgw [label="RTP-AMR[seq=p+3,ssrc=s] (originally seq=y+3,ssrc=MSb)"];
bscnat => mgw [label="RTP-AMR[seq=o+4,ssrc=r] (originally seq=x+4,ssrc=MSa)"];
bscnat => mgw [label="RTP-AMR[seq=p+4,ssrc=s] (originally seq=y+4,ssrc=MSb)"];
bscnat => mgw [label="RTP-AMR[seq=o+5,ssrc=r] (originally seq=x+5,ssrc=MSa)"];
bscnat => mgw [label="RTP-AMR[seq=p+5,ssrc=s] (originally seq=y+5,ssrc=MSb)"];
}
----
=== Marker bit
As described earlier, the Marker bit is always expected to relate to the first
AMR payload of an OSmux frame. Thus, special considerations may be followed when
the OSmux encoder receives an RTP packet with a marker bit. For instance,
previously enqueued RTP packets may be sent even if the configured batch factor
is not reached.
We again use the scenario with 2 concurrent calls and a batch factor of 3.
["mscgen"]
----
msc {
hscale = 2;
bts [label="BTS"], bsc [label="BSC"], bscnat [label="BSC-NAT"], mgw [label="MGW"];
...;
--- [label="2 Regular RTP-AMR call using OSmux with batch factor 3 (has been ongoing for some time)"];
bts => bsc [label="RTP-AMR[seq=x,ssrc=MSa]"];
bts => bsc [label="RTP-AMR[seq=y,ssrc=MSb]"];
bts => bsc [label="RTP-AMR[seq=x+1,ssrc=MSa]"];
bts => bsc [label="RTP-AMR[seq=y+1,ssrc=MSb]"];
bts => bsc [label="RTP-AMR[seq=x+2,ssrc=MSa]"];
bts => bsc [label="RTP-AMR[seq=y+2,ssrc=MSb]"];
bsc => bscnat [label="UDP[Osmux[ft=2,cid=i,seq=m,AMR(x),AMR(x+1),AMR(x+2)],Osmux[ft=2,cid=i+1,seq=n,AMR(y),AMR(y+1),AMR(y+2)]]"];
bscnat => mgw [label="RTP-AMR[seq=o,ssrc=r] (originally seq=x,ssrc=MSa)"];
bscnat => mgw [label="RTP-AMR[seq=p,ssrc=r] (originally seq=y,ssrc=MSb)"];
bscnat => mgw [label="RTP-AMR[seq=o+1,ssrc=r] (originally seq=x+1,ssrc=MSa)"];
bscnat => mgw [label="RTP-AMR[seq=p+1,ssrc=s] (originally seq=y+1,ssrc=MSb)"];
bscnat => mgw [label="RTP-AMR[seq=o+2,ssrc=r] (originally seq=x+2,ssrc=MSa)"];
bscnat => mgw [label="RTP-AMR[seq=p+2,ssrc=s] (originally seq=y+2,ssrc=MSb)"];
bts => bsc [label="RTP-AMR[seq=x+3,ssrc=MSa]"];
bts => bsc [label="RTP-AMR[seq=y+3,ssrc=MSb]"];
bts => bsc [label="RTP-AMR[seq=x+4,ssrc=MSa]"];
bts => bsc [label="RTP-AMR[seq=y+4,ssrc=MSb] with Marker bit set M=1"];
bsc => bscnat [label="UDP[Osmux[ft=2,cid=i,seq=m+1,AMR(x+3),AMR(x+4)],Osmux[ft=2,cid=i+1,seq=n+1,AMR(y+3)]]"];
bscnat => mgw [label="RTP-AMR[seq=o+3,ssrc=r] (originally seq=x+3,ssrc=MSa)"];
bscnat => mgw [label="RTP-AMR[seq=p+3,ssrc=s] (originally seq=y+3,ssrc=MSb)"];
bscnat => mgw [label="RTP-AMR[seq=o+4,ssrc=r] (originally seq=x+4,ssrc=MSa)"];
bts => bsc [label="RTP-AMR[seq=x+5,ssrc=MSa]"];
bts => bsc [label="RTP-AMR[seq=y+5,ssrc=MSb]"];
bts => bsc [label="RTP-AMR[seq=x+6,ssrc=MSa]"];
bts => bsc [label="RTP-AMR[seq=y+6,ssrc=MSb]"];
bsc => bscnat [label="UDP[Osmux[ft=2,cid=i,seq=m+2,AMR(x+5),AMR(x+6)],Osmux[ft=2,cid=i+1,seq=n+2,AMR(y+4),AMR(y+5),AMR(y+6)]]"];
bscnat => mgw [label="RTP-AMR[seq=p+4,ssrc=s] (originally seq=y+4,ssrc=MSb)"];
bscnat => mgw [label="RTP-AMR[seq=o+5,ssrc=r] (originally seq=x+5,ssrc=MSa)"];
bscnat => mgw [label="RTP-AMR[seq=p+5,ssrc=s] (originally seq=y+5,ssrc=MSb)"];
bscnat => mgw [label="RTP-AMR[seq=o+6,ssrc=r] (originally seq=x+6,ssrc=MSa)"];
bscnat => mgw [label="RTP-AMR[seq=p+6,ssrc=s] (originally seq=y+6,ssrc=MSb)"];
}
----
== Evaluation: Expected traffic savings
The following figure shows the growth in traffic saving (in %) depending on the
number of concurrent numbers of callings for a given set of batching factor
values:
["python2"]
----
from pychart import *
theme.get_options()
theme.scale_factor = 5
theme.use_color = 1
theme.reinitialize()
IP_HEADER=20
UDP_HEADER=8
RTP_HEADER=12
OSMUX_HEADER=4
AMR59_PAYLOAD=17
def osmux_get_size(calls, payloads):
return IP_HEADER + UDP_HEADER + (OSMUX_HEADER + AMR59_PAYLOAD * payloads) * calls
def rtp_get_size(calls, payloads):
return calls * payloads * (IP_HEADER + UDP_HEADER + RTP_HEADER + AMR59_PAYLOAD)
def calc_traffic_saving(calls, payloads):
return 100 - 100.0 * osmux_get_size(calls, payloads) / rtp_get_size(calls, payloads)
# The first value in each tuple is the X value, and subsequent values are Y values for different lines.
def gen_table():
data = []
for calls in range(1, 9):
col = (calls,)
for factor in range(1, 9):
col += (calc_traffic_saving(calls, factor),)
data.append(col)
return data
def do_plot(data):
xaxis = axis.X(format="/hL%d", tic_interval = 1, label="Concurrent calls")
yaxis = axis.Y(format="%d%%", tic_interval = 10, label="Traffic Saving")
ar = area.T(x_axis=xaxis, y_axis=yaxis, y_range=(None,None), x_grid_interval=1, x_grid_style=line_style.gray70_dash3)
for y in range(1, len(data[0])):
plot = line_plot.T(label="bfactor "+str(y), data=data, ycol=y, tick_mark=tick_mark.circle1)
ar.add_plot(plot)
ar.draw()
data = gen_table()
do_plot(data)
----
The results show a saving of 15.79% with only one concurrent call and with
batching disabled (bfactor 1), that quickly improves with more concurrent calls
(due to trunking).
By increasing the batching of messages to 4, the results show a saving of 56.68%
with only one concurrent call. Trunking slightly improves the situation with
more concurrent calls.
A batching factor of 8 provides very little improvement with regards to batching
4 messages. Still, we risk to degrade user experience. Thus, we consider a
batching factor of 3 and 4 is adecuate.
== Other proposed follow-up works
The following sections describe features that can be considered in the mid-run
to be included in the OSmux infrastructure. They will be considered for future
proposals as extensions to this work. Therefore, they are NOT included in
this proposal.
=== Encryption
Voice streams within OSmux can be encrypted in a similar manner to SRTP
(RFC3711). The only potential problem is the use of a reduced sequence number,
as it wraps in (20ms * 2^256 * B), i.e. 5.12s to 40.96s. However, as the
receiver knows at which rate the codec frames are generated at the sender, he
should be able to compute how much time has passed using his own timebase.
Another alternative can be the use of DTLS (RFC 6347) that can be used to
secure datagram traffic using TLS facilities (libraries like openssl and
gnutls already support this).
=== Multiple OSmux messages in one packet
In case there is already at least one active voice call, there will be
regular transmissions of voice codec frames. Depending on the batching
factor, they will be sent every 70ms to 140ms. The size even of a
batched (and/or trunked) codec message is still much lower than the MTU.
Thus, any signalling (related or unrelated to the call causing the codec
stream) can just be piggy-backed to the packets containing the voice
codec frames.

10
doc/manuals/vty/bsc_vty_additions.xml Normal file
View File

@ -0,0 +1,10 @@
<vtydoc xmlns='urn:osmocom:xml:libosmocore:vty:doc:1.0'>
<node id='config-msc'>
<description>This node allows to configure the MSC connection related
settings.</description>
</node>
<node id='config-bsc'>
<description>This node allows to configure the BSC connection related
settings.</description>
</node>
</vtydoc>

4846
doc/manuals/vty/bsc_vty_reference.xml Normal file
View File

File diff suppressed because it is too large Load Diff

244
doc/manuals/vty/libbsc_vty_additions.xml Normal file
View File

@ -0,0 +1,244 @@
<vtydoc xmlns='urn:osmocom:xml:libosmocore:vty:doc:1.0'>
<node id='14'>
<child_of nodeid='4' />
<name>GSM Network Configuration</name>
<description>This is the base node for all configuration of
GSM network related configuration, it includes the LAC, CI
access criteria but also the configuration of each BTS in this
network.</description>
</node>
<node id='15'>
<child_of nodeid='14' />
<name>BTS Configuration</name>
<description>This is the configuration of a single BTS.</description>
<command id='oml ip.access stream_id &lt;0-255&gt; line E1_LINE'>
<description>
Set the IPA stream identifier for the OML link within the IPA
multiplex. Must be the same as on the BTS side. The default
value is 255. Only applies to BTSs connected via Abis/IP
interface.
</description>
</command>
<command id='is-connection-list (add|del) &lt;0-2047&gt; &lt;0-2047&gt; &lt;0-255&gt;'>
<description>
Only applies to Ericsson OML2000 based BTSs.
</description>
</command>
<command id='con-connection-list (add|del) &lt;1-255&gt; &lt;0-1023&gt; deconcentrated'>
<description>
Only applies to Ericsson OML2000 based BTSs.
</description>
</command>
<command id='con-connection-list (add|del) &lt;1-255&gt; &lt;0-1023&gt; tei &lt;0-63&gt;'>
<description>
Only applies to Ericsson OML2000 based BTSs.
</description>
</command>
<command id='channel-descrption attach (0|1)'>
<description>
Configure whether the IMSI ATTACH (and DETACH) procedures
shall be used by MS in this cell. The default should be enabled.
</description>
</command>
<command id='ip.access rsl-ip A.B.C.D'>
<description>
Configure the IP address of the BSC used for RSL. Abis/IP
BTSs, including OsmoBTS and the nanoBTS will be instructed to
connect their RSL links to that IP address.
</description>
</command>
<command id='base_station_id_code &lt;0-63&gt;'>
<description>
Configure the BSIC of the cell. It is a 6-bit value
consisting of a 3-bit NCC (network color code) in the upper 3
bits, and a 3-bit BCC (base station color code) in the lower 3
bits.
</description>
</command>
<command id='training_sequence_code &lt;0-7&gt;'>
<description>
Configure the default TSC for all timeslots on all TRX of the BTS.
The normal default is to use the BCC part of the BSIC as TSC.
Not all BTS models support a TSC != BCC.
</description>
</command>
<command id='si5 neighbor-list (add|del) arfcn &lt;0-1023&gt;'>
<description>
Add or remove an ARFCN to/from the list of neighbor cells
advertised in dedicated mode via SACCH. This command is only
available in manual-si5 neighbor-list mode.
</description>
</command>
<command id='neighbor-list (add|del) arfcn &lt;0-1023&gt;'>
<description>
Add or remove an ARFCN to/from the list of neighbor cells.
This command is only available in manual neighbor-list mode.
</description>
</command>
<command id='gprs network-control-order (nc0|nc1|nc2)'>
<description>
</description>
</command>
<command id='cell reselection offset &lt;0-126&gt;'>
<description>
If a cell advertises a cell reselection offset (CRO), it will
become more attractive during cell re-selection, despite not
being received at a higher level than other cells. The CRO
of each neighbor cell is added to the respective received
signal level before comparing their values for re-selection.
</description>
</command>
<command id='cell reselection hysteresis &lt;0-14&gt;'>
<description>
The Cell Re-Selection Hysteresis determines how many dB a
neighbor cell must be stronger than the current serving cell
before the MS considers that neighbor cell as a candidate for
re-selection.
</description>
</command>
<command id='ip.access unit_id &lt;0-65534&gt; &lt;0-255&gt;'>
<description>
The ip.access unit ID is a parameter of the IPA
Signalling-over-IP multiplex. It is administratively
configured on the BTS side, and used by the BTS to identify
itself to the BSC. The BSC then selects the BTS configuration
for this Unit ID. It consists of three parts, the Site ID,
the BTS ID and the TRX ID. The TRX ID automatically
corresponds to to the transceiver number and is thus not
configurable here.
</description>
</command>
<command id='ms max power &lt;0-40&gt;'>
<description>
Configures the maximum transmit power (in dBm) that any MS may
use within this cell.
</description>
</command>
<command id='periodic location update &lt;6-1530&gt;'>
<description>
The periodic location updating interval determines how often
the MS will periodically perform a LOCATION UPDATE procedure,
despite not having actuall changed location. The value is
specified in minutes.
</description>
</command>
<command id='cell barred (0|1)'>
<description>
Using this command, you can enable/disable barring of the cell.
Barred cells are not visible/accessible to regular phones.
Only some special operator testing phones can be configured in
a way to ignore cell barring.
</description>
</command>
<command id='rxlev access min &lt;0-63&gt;'>
<description>
Using this command, you can determine the minimum downlink
signal receive level (RxLev), at which the BTS must be
received by the MS in order to attempt establishing dedicated
channels via the RACH.
</description>
</command>
<command id='rach access-control-class (0|1|2|3|4|5|6|7|8|9|11|12|13|14|15) (barred|allowed)'>
<description>
Using this command, you can configure which access control
classes are permitted to access this cell. The access control
class of a MS is determined by the contents of the EF.ACC file
on the SIM card.
Access Control Class 10 corresponds to Emergency Calls, and is
thus not configurable this way.
</description>
</command>
<command id='rach emergency call allowed (0|1)'>
<description>
Using this command, you can determine if this cell permits the
use of the 'EMERGENCY CALL' feature.
<warning>Unless you operate a public network with connection to the
public emergency services in compliance with applicable regulatory
requirements, you should always have emergency calls disabled (allowed
0) - which is also the default configuration.</warning>
</description>
</command>
<command id='channel-descrption bs-ag-blks-res &lt;0-7&gt;'>
<description>
Using this command, you can specify how many blocks of the
downlink CCCH should be reserved for exclusive usage as AGCH.
<warning>Not all BTS models currently support non-default configuration
of this parameter.</warning>
</description>
</command>
<command id='oml e1 tei &lt;0-63&gt;'>
<description>
Set the LAPD TEI used for the OML connection of this BTS.
Only applies to classic E1 based A-bis.
</description>
</command>
</node>
<node id='16'>
<child_of nodeid='15' />
<name>TRX Configuration</name>
<description>This is the configuration of a TRX.</description>
<command id='nominal power &lt;0-100&gt;'>
<description>
Inform the BSC about the nominal RF transmit power of the BTS in dBm.
This value must be entered depending on the BTS model and
external setup such as amplifiers. Changing this value will
not change the actually transmitted power, it will just affect
the reporting in the BSC VTY.
</description>
</command>
<command id='max_power_red &lt;0-100&gt;'>
<description>
Request the actual RF transmit power of the BTS to be reduced
by the specified number of dB.
</description>
</command>
<command id='rsl e1 tei &lt;0-63&gt;'>
<description>
Set the LAPD TEI used for the RSL connection of this TRX.
Only applies to classic E1 based A-bis.
</description>
</command>
<command id='rf_locked (0|1)'>
<description>
Enable (1) or disable (0) the RF locking for this TRX. RF
locking is a mechanism by which the transmitter can be shut
down by administrative means, e.g. via the control interface.
</description>
</command>
</node>
<node id='17'>
<child_of nodeid='16' />
<name>TS Configuration</name>
<description>This is the configuration of a TS.</description>
<command id='training_sequence_code &lt;0-7&gt;'>
<description>
Configure the timeslot to run on a different TSC than the
default TSC of the BTS (which is derived from the BCC part of the BSIC).
Please note that not all BTS models support timeslot-specific TSC!
</description>
</command>
<command id='hopping enabled (0|1)'>
<description>
Enable or disable frequency hopping for this timeslot. Please
note that not all BTS models may support frequency hopping,
and that frequency hopping is only permitted for secondary
TRXs, so TRX 0 must always be non-hopping.
</description>
</command>
</node>
<node id='22'>
<child_of nodeid='3' />
<name>OML Commands</name>
<description>This node allows to manipulate the OML state of
a connected BTS. It is meant for testing during development.</description>
</node>
<node id='26'>
<child_of nodeid='3' />
<name>OML2000 Commands</name>
<description>This node allows to issue OML2000 commands for
Ericsson BTS. It is meant for testing during development.</description>
</node>
</vtydoc>