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

initial checkin of manuals to public repo 

The manuals existed in different form for several years in an internal
sysmocom repository.  However, since they had just recently been
converted from docboox-xml to asciidoc and all files have been
re-shuffled for enabling the public release, there's not much point in
keeping the history with git-filter-branch.
This commit is contained in:
Harald Welte 2016-02-20 10:56:10 +01:00 committed by Neels Hofmeyr
parent a6a18b66ee
commit 524fdd3ac8
26 changed files with 3279 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
doc/manuals/Makefile Normal file
View File

@ -0,0 +1,14 @@
TOPDIR := ..
ASCIIDOCS := osmobts-usermanual osmobts-abis
include $(TOPDIR)/build/Makefile.asciidoc.inc
# for the upload target
include $(TOPDIR)/build/Makefile.inc
# dependencies
osmobts-abis.pdf: abis/*.adoc abis/*.msc
osmobts-usermanual.pdf: chapters/*.adoc
clean:
rm -rf $(cleanfiles)

23
doc/manuals/abis/abis-startup.msc Normal file
View File

@ -0,0 +1,23 @@
msc {
bts [label="BTS"], bsc [label="BSC"];
bts => bsc [label="TCP Connect (Port 3002, OML)"];
bts box bsc [label="IPA CCM Identification (Port 3002)"];
bts <= bsc [label="OML Configuration of BTS via OML"];
...;
bts <= bsc [label="OML (TRX=0) IPA RSL CONNECT"];
bts => bsc [label="TCP Connect (Port 3003, RSL, TRX 0)"];
bts box bsc [label="IPA CCM Identification Port 3003"];
bts <= bsc [label="RSL BCCH filling (System Information)"];
bts <= bsc [label="RSL SACCH filling (SI 5/6)"];
...;
bts <= bsc [label="OML (TRX=1) IPA RSL CONNECT"];
bts => bsc [label="TCP Connect (Port 3003, RSL, TRX 1)"];
bts box bsc [label="IPA CCM Identification (Port 3003)"];
bts <= bsc [label="RSL SACCH filling (SI 5/6)"];
...;
bts <= bsc [label="OML (TRX=N) IPA RSL CONNECT"];
bts => bsc [label="TCP Connect (Port 3003, RSL, TRX N)"];
bts box bsc [label="IPA CCM Identification (Port 3003)"];
bts <= bsc [label="RSL SACCH filling (SI 5/6)"];
}

106
doc/manuals/abis/ipa.adoc Normal file
View File

@ -0,0 +1,106 @@
== IPA Multiplex
The ETSI/3GPP specifications for A-bis transport (ETSI/3GPP TS 08.56)
specify the transmission of RSL and OML messages over a LAPD based
framing on top of 64kBit/s signalling times slots (B-channels) on E1
lines.
OsmoBTS does not implement this LAPD based transport, but instead
implements A-bis over IP in a flavor first observed by ip.access nanoBTS
products. The OsmoBTS implementation is a clean-room re-implementation
based on the observation and dissection of protocol traces.
LAPD as used in E1 signalling channels provides in-order transmission
and reliable delivery. This is why TCP was chosen as Layer 4 transport
protocol on top of IP. TCP however, is a stream based transport
protocol, which doesn't preserve the boundaries of messages.
To work around this shortcoming, an additional framing layer called the
IPA multiplex was introduced between TCP and the RSL and OML messages.
.Protocol Stacking
[width="30%"]
|===
|RSL + OML (this document)
|IPA (this document)
|TCP (IETF RFC 793)
|IP (IETF RFC 791)
|Ethernet (IEEE 802.3)
|===
=== IPA Header
Each higher-layer PDU is encapsulated by a three-byte IPA header with
the following structure:
.IPA Header Structure
[options="header",cols="10%,15%,15%,60%"]
|===
|Offset (Octets)|Length|Name|Description
|0|2|Length|Length of the variable-length payload section in network
byte order (excluding the length of the IPA Header)
|2|1|Stream Identifier|Identifies the stream of the payload
|3|Variable|Payload|higher-layer PDU (i.e. RSL or OML message)
|===
=== IPA Stream Identifiers
The IPA Stream Identifier serves to differentiate different streams
within the multiplex. In the context of A-bis, it can be seen as
analogous to the LAPD TEI on classic A-bis over E1.
The following IPA stream identifiers are being used in A-bis/IP:
.IPA Stream Identifiers
[options="header",width="70%",cols="20%,20%,60%"]
|===
|Value (Hex)|Name|Description
|0x00|RSL|A-bis RSL according to this document, TRX 0
|0x01|RSL|A-bis RSL according to this document, TRX 1
|0x0n|RSL|A-bis RSL according to this document, TRX n
|0xfe|CCM|IPA Connection Management
|0xff|OML|A-bis OML according to this document
|===
=== IPA Connection Management (CCM)
The IPA Connection Management is a sub-layer underneath the IPA
multiplex which is used to manage the connection itself. It supports
functions like Identity Management and Keep-Alive.
==== Identity Management
When a BTS connects to the BSC, the BSC must identify the connected BTS
somehow. In ETSI/3GPP A-bis, the E1 multiplex + signalling timeslot
number is used for this. In IP, there is no similar usable identity.
Hence, the Unit ID is used for this purpose.
.Procedure for IPA peer identification is as follows
[options="header",cols="20%,80%"]
|===
|Direction|Operation
|BTS -> BSC|BTS connects the TCP connection to be used with IPA
|BTS <- BSC|BSC requests BTS identity with ID_GET
|BTS -> BSC|BTS responds BTS Unit ID with ID_RESP
|BTS <- BSC|BSC responds with ID_ACK, if the Unit ID is known to the BSC
|===
Following the above peer identification procedure, transfer of
higher-level messages such as OML or RSL commences.
==== IPA CCM Messages
IPA CCM supports the following messages
.IPA CCM Messages
[options="header"]
[cols="10%,15%,75%"]
|===
|Value|Name|Purpose
|0x00|PING|Request a PONG from the peer
|0x01|PONG|Response to a PING
|0x04|ID_GET|Request Identity from peer
|0x05|ID_RESP|Response to ID_GET
|0x06|ID_ACK|Identity Acknowledged
|===

26
doc/manuals/abis/oml-mo-bts.msc Normal file
View File

@ -0,0 +1,26 @@
msc {
bts [label="BTS"], bsc [label="BSC"];
# this is for the BTS Object
--- [label="Initial state after establishing OML"];
bts => bsc [label="STATE CHG REP (Disabled/Notinstalled/Locked)"];
--- [label="MO requests software activation"];
bts => bsc [label="SW Activate Req"];
bts <= bsc [label="SW Activate Req Ack"];
--- [label="BTS instructs BTS to activate software"];
bts <= bsc [label="Activate SW"];
bts => bsc [label="Activate SW Ack"];
--- [label="MO reports new state after SW activation"];
bts => bsc [label="STATE CHG REP (Disabled/Dependency)"];
bts => bsc [label="SW Activated Report"];
--- [label="Configure the MO with its attributes"];
bts <= bsc [label="Set BTS Attributes"];
bts => bsc [label="Set BTS Attributes Ack"];
bts <= bsc [label="OPSTART"];
bts => bsc [label="OPSTART ACK"];
--- [label="As this object is locked, we need to unlock it"];
bts <= bsc [label="Change Adm State (Unlocked)"];
bts => bsc [label="Change Adm State Ack (Unlocked)"];
bts => bsc [label="STATE CHG REP (Disabled/Dependency/Unlocked)"];
--- [label="Initialize Radio Transceiver, Radio Carrier, Channels"];
bts => bsc [label="STATE CHG REP (Enabled/OK)"];
}

24
doc/manuals/abis/oml-mo-carrier.msc Normal file
View File

@ -0,0 +1,24 @@
msc {
bts [label="Radio Carrier"], bsc [label="BSC"];
--- [label="Initial state after establishing OML"];
bts => bsc [label="STATE CHG REP (Disabled/Notinstalled/Locked)"];
--- [label="MO requests software activation"];
bts => bsc [label="SW Activate Req"];
bts <= bsc [label="SW Activate Req Ack"];
--- [label="BTS instructs BTS to activate software"];
bts <= bsc [label="Activate SW"];
bts => bsc [label="Activate SW Ack"];
--- [label="MO reports new state after SW activation"];
bts => bsc [label="STATE CHG REP (Disabled/Offline)"];
bts => bsc [label="SW Activated Report"];
--- [label="Configure the MO with its attributes"];
bts <= bsc [label="Set Radio Carrier Attributes"];
bts => bsc [label="Set Radio Carrier Attributes Ack"];
bts <= bsc [label="OPSTART"];
bts => bsc [label="OPSTART ACK"];
--- [label="As this object is locked, we need to unlock it"];
bts <= bsc [label="Change Adm State (Unlocked)"];
bts => bsc [label="Change Adm State Ack (Unlocked)"];
bts => bsc [label="STATE CHG REP (Disabled/OK/Unlocked)"];
bts => bsc [label="STATE CHG REP (Enabled)"];
}

20
doc/manuals/abis/oml-mo-channel.msc Normal file
View File

@ -0,0 +1,20 @@
msc {
bts [label="Channel"], bsc [label="BSC"];
--- [label="Initial state after establishing OML"];
bts => bsc [label="STATE CHG REP (Disabled/Notinstalled/Locked)"];
--- [label="MO reports new state after SW activation of Baseband Transceiver"];
bts => bsc [label="STATE CHG REP (Disabled/Dependency)"];
bts => bsc [label="SW Activated Report"];
--- [label="Configure the MO with its attributes"];
bts <= bsc [label="Set Channel Attributes"];
bts => bsc [label="Set Channel Attributes Ack"];
bts <= bsc [label="OPSTART"];
bts => bsc [label="OPSTART ACK"];
--- [label="As this object is locked, we need to unlock it"];
bts <= bsc [label="Change Adm State (Unlocked)"];
bts => bsc [label="Change Adm State Ack (Unlocked)"];
bts => bsc [label="STATE CHG REP (Disabled/Dependency/Unlocked)"];
--- [label="Initialize Radio Carrier / Baseband Transceiver"];
bts => bsc [label="STATE CHG REP (Disabled/Offline)"];
bts => bsc [label="STATE CHG REP (Enabled/OK)"];
}

17
doc/manuals/abis/oml-mo-sitemgr.msc Normal file
View File

@ -0,0 +1,17 @@
msc {
bts [label="Site Manager"], bsc [label="BSC"];
# this is for the Site Manager Object
--- [label="Initial state after establishing OML"];
bts => bsc [label="STATE CHG REP (Disabled/Notinstalled)"];
--- [label="MO requests software activation"];
bts => bsc [label="SW Activate Req"];
bts <= bsc [label="SW Activate Req Ack"];
--- [label="BTS instructs BTS to activate software"];
bts <= bsc [label="Activate SW"];
bts => bsc [label="Activate SW Ack"];
--- [label="MO reports new state after SW activation"];
bts => bsc [label="STATE CHG REP (Enabled)"];
bts => bsc [label="SW Activated Report"];
bts <= bsc [label="OPSTART"];
bts => bsc [label="OPSTART ACK"];
}

23
doc/manuals/abis/oml-mo-transceiver.msc Normal file
View File

@ -0,0 +1,23 @@
msc {
bts [label="Baseband Transceiver"], bsc [label="BSC"];
--- [label="Initial state after establishing OML"];
bts => bsc [label="STATE CHG REP (Disabled/Notinstalled/Locked)"];
--- [label="MO requests software activation"];
bts => bsc [label="SW Activate Req"];
bts <= bsc [label="SW Activate Req Ack"];
--- [label="BTS instructs BTS to activate software"];
bts <= bsc [label="Activate SW"];
bts => bsc [label="Activate SW Ack"];
--- [label="MO reports new state after SW activation"];
bts => bsc [label="STATE CHG REP (Disabled/Dependency)"];
bts => bsc [label="SW Activated Report"];
--- [label="BSC requests RSL establishment"];
bts <= bsc [label="IPA RSL Connect"];
bts => bsc [label="IPA RSL Connect ACK"];
bts <= bsc [label="OPSTART"];
bts => bsc [label="OPSTART ACK"];
--- [label="As this object is locked, we need to unlock it"];
bts <= bsc [label="Change Adm State (Unlocked)"];
bts => bsc [label="Change Adm State Ack (Unlocked)"];
bts => bsc [label="STATE CHG REP (Disabled/Dependency/Unlocked)"];
}

34
doc/manuals/abis/oml-startup.msc Normal file
View File

@ -0,0 +1,34 @@
msc {
hscale = 2;
chan [label="Channel"], rc [label="Radio Carrier"], smg [label="Site Manager"], bts [label="BTS"], bsc [label="BSC"];
bts => bsc [label="TCP Connect (Port 3003, OML)"];
bts box bsc [label="IPA CCM Identification (Port 3003)"];
|||;
smg => bsc [label="(Site Mgr) STATE CHG REP (Disabled/NotInstalled)"];
bts => bsc [label="(BTS) STATE CHG REP (Disabled/NotInstalled/Locked)"];
rc => bsc [label="(TRANSC) STATE CHG REP (Disabled/NotInstalled/Locked)"];
chan => bsc [label="(Ch 0) STATE CHG REP (Disabled/NotInstalled/Locked)"];
chan => bsc [label="(Ch 1) STATE CHG REP (Disabled/NotInstalled/Locked)"];
chan => bsc [label="(Ch 2) STATE CHG REP (Disabled/NotInstalled/Locked)"];
chan => bsc [label="(Ch 3) STATE CHG REP (Disabled/NotInstalled/Locked)"];
chan => bsc [label="(Ch 4) STATE CHG REP (Disabled/NotInstalled/Locked)"];
chan => bsc [label="(Ch 5) STATE CHG REP (Disabled/NotInstalled/Locked)"];
chan => bsc [label="(Ch 6) STATE CHG REP (Disabled/NotInstalled/Locked)"];
chan => bsc [label="(Ch 7) STATE CHG REP (Disabled/NotInstalled/Locked)"];
rc => bsc [label="(RC) STATE CHG REP (Disabled/NotInstalled/Locked)"];
bts => bsc [label="(GPRS-NSE) STATE CHG REP (Disabled/NotInstalled/Locked)"];
bts => bsc [label="(GPRS-CELL) STATE CHG REP (Disabled/NotInstalled/Locked)"];
bts => bsc [label="(GPRS-NSVC0) STATE CHG REP (Disabled/NotInstalled/Locked)"];
bts => bsc [label="(GPRS-NSVC1) STATE CHG REP (Disabled/NotInstalled/Locked)"];
|||;
smg => bsc [label="(Site Mgr) SW Activate Req"];
smg <= bsc [label="(Site Mgr) SW Activate Req Ack"];
smg <= bsc [label="(Site Mgr) Activate SW"];
smg => bsc [label="(Site Mgr) Activate SW Ack"];
smg => bsc [label="(Site Mgr) STATE CHG REP (Enabled)"];
smg => bsc [label="(Site Mgr) SW Activated Report"];
smg <= bsc [label="(Site Mgr) OPSTART"];
smg => bsc [label="(Site Mgr) OPSTART ACK"];
}

50
doc/manuals/abis/oml-startup2.msc Normal file
View File

@ -0,0 +1,50 @@
msc {
hscale = 2;
chan [label="Channel"], rc [label="Radio Carrier"], bts [label="BTS"], bsc [label="BSC"];
bts box bsc [label="OML Connect + Site Manager Init"];
...;
bts => bsc [label="(BTS) SW Activate Req"];
bts <= bsc [label="(BTS) SW Activate Req Ack"];
bts <= bsc [label="(BTS) Activate SW"];
bts => bsc [label="(BTS) Activate SW Ack"];
bts => bsc [label="(BTS) STATE CHG REP (Disabled/Dependency)"];
bts => bsc [label="(BTS) SW Activated Report"];
|||;
rc => bsc [label="(TRANSC) SW Activate Req"];
rc => bsc [label="(RC) SW Activated Req"];
|||;
bts <= bsc [label="(BTS) Set BTS Attributes"];
bts => bsc [label="(BTS) Set BTS Attributes Ack"];
bts <= bsc [label="(BTS) OPSTART"];
bts => bsc [label="(BTS) OPSTART Ack"];
|||;
bts <= bsc [label="(BTS) Change Adm State (Unlocked)"];
bts => bsc [label="(BTS) Change Adm State ACK (Unlocked)"];
bts => bsc [label="(BTS) STATE CHG REP (Disabled/Dependency/Unlcoked)"];
|||;
rc <= bsc [label="(TRANSC) SW Activate Req Ack"];
rc <= bsc [label="(TRANSC) Activate SW"];
rc => bsc [label="(TRANSC) Activate SW Ack"];
rc => bsc [label="(TRANSC) STATE CHG REP (Disabled/Dependency)"];
rc => bsc [label="(TRANSC) SW Activated Report"];
chan => bsc [label="(CHAN 0) STATE CHG REP (Disabled/Dependency)"];
chan => bsc [label="(CHAN 1) STATE CHG REP (Disabled/Dependency)"];
chan => bsc [label="(CHAN 2) STATE CHG REP (Disabled/Dependency)"];
chan => bsc [label="(CHAN 3) STATE CHG REP (Disabled/Dependency)"];
chan => bsc [label="(CHAN 4) STATE CHG REP (Disabled/Dependency)"];
chan => bsc [label="(CHAN 5) STATE CHG REP (Disabled/Dependency)"];
chan => bsc [label="(CHAN 6) STATE CHG REP (Disabled/Dependency)"];
chan => bsc [label="(CHAN 7) STATE CHG REP (Disabled/Dependency)"];
|||;
chan => bsc [label="(CHAN 0) SW Activated Report"];
chan => bsc [label="(CHAN 1) SW Activated Report"];
chan => bsc [label="(CHAN 2) SW Activated Report"];
chan => bsc [label="(CHAN 3) SW Activated Report"];
chan => bsc [label="(CHAN 4) SW Activated Report"];
chan => bsc [label="(CHAN 5) SW Activated Report"];
chan => bsc [label="(CHAN 6) SW Activated Report"];
chan => bsc [label="(CHAN 7) SW Activated Report"];
}

51
doc/manuals/abis/oml-startup3.msc Normal file
View File

@ -0,0 +1,51 @@
msc {
hscale = 2;
chan [label="Channel"], rc [label="Radio Carrier"], bts [label="BTS"], bsc [label="BSC"];
...;
rc <= bsc [label="(RC) SW Activate Req Ack"];
rc <= bsc [label="(RC) Activate SW"];
rc => bsc [label="(RC) Activate SW Ack"];
rc => bsc [label="(RC) STATE CHG REP (Disabled/Offline)"];
rc => bsc [label="(RC) SW Activated Report"];
rc <= bsc [label="(TRANSC) IPA RSL Connect"];
rc => bsc [label="(TRANSC) IPA RSL Connect Ack"];
rc <= bsc [label="(TRANSC) OPSTART"];
rc => bsc [label="(TRANSC) OPSTART Ack"];
rc <= bsc [label="(TRANSC) Change Adm State (Unlocked)"];
rc => bsc [label="(TRANSC) Change Adm State Ack (Unlocked)"];
rc => bsc [label="(TRANSC) STATE CHG REP (Disabled/Dependency/Unlocked)"];
|||;
chan <= bsc [label="(CHAN 0) Set Channel Attributes"];
chan => bsc [label="(CHAN 0) Set Channel Attributes Ack"];
chan <= bsc [label="(CHAN 0) OPSTART"];
chan => bsc [label="(CHAN 0) OPSTART Ack"];
chan <= bsc [label="(CHAN 0) Change Adm State (Unlocked)"];
chan => bsc [label="(CHAN 0) Change Adm State Ack (Unlocked)"];
chan => bsc [label="(CHAN 0) STATE CHG REP (Disabled/Dependency/Unlocked)"];
...;
chan <= bsc [label="(CHAN 7) Set Channel Attributes"];
chan => bsc [label="(CHAN 7) Set Channel Attributes Ack"];
chan <= bsc [label="(CHAN 7) OPSTART"];
chan => bsc [label="(CHAN 7) OPSTART Ack"];
chan <= bsc [label="(CHAN 7) Change Adm State (Unlocked)"];
chan => bsc [label="(CHAN 7) Change Adm State Ack (Unlocked)"];
chan => bsc [label="(CHAN 7) STATE CHG REP (Disabled/Dependency/Unlocked)"];
|||;
rc <= bsc [label="(RC) Set Radio Carrier Attributes"];
rc => bsc [label="(RC) Set Radio Carrier Attributes Ack"];
rc <= bsc [label="(RC) OPSTART"];
rc => bsc [label="(RC) OPSTART Ack"];
rc <= bsc [label="(RC) Change Adm State (Unlocked)"];
rc => bsc [label="(RC) Change Adm State Ack (Unlocked)"];
rc => bsc [label="(RC) STATE CHG REP (Disabled/OK/Unlocked)"];
rc => bsc [label="(RC) STATE CHG REP (Enabled)"];
rc => bsc [label="(TRANSC) STATE CHG REP (Disabled/Offline)"];
rc => bsc [label="(TRANSC) STATE CHG REP (Enabled/OK)"];
|||;
chan => bsc [label="(CHAN 0) STATE CHG REP (Disabled/Offline)"];
chan => bsc [label="(CHAN 0) STATE CHG REP (Enabled/OK)"];
|||;
bts => bsc [label="(BTS) STATE CHG REP (Enabled/OK)"];
}

937
doc/manuals/abis/oml.adoc Normal file
View File

@ -0,0 +1,937 @@
== Organization & Maintenance Link (OML)
=== List of Messages
The following tables list the OML messages used by OsmoBTS, grouped by their
level of compliance with 3GPP TS 12.21.
==== Messages Compliant With TS 12.21
Specific limitations apply, see the linked sections.
.Messages compliant with TS 12.21
[options="header",cols="10%,10%,20%,35%,5%,20%"]
|===
| TS 12.21 § | type code (hex) | This document § | Message | <-/-> | Received/Sent by OsmoBTS
6+<| *SW Download Management Messages:*
| 8.3.7 | 0x10 | <<sw_act_rep>> | SW Activated Report | -> | Sent
6+<| *Air Interface Management Messages:*
.3+.| 8.6.1 | 0x41 .3+.| <<set_bts_attr>> | Set BTS Attributes | <- | Received
| 0x42 | Set BTS Attributes Ack | -> | Sent
| 0x43 | Set BTS Attributes Nack | -> | Sent
.3+.| 8.6.2 | 0x44 .3+.| <<set_radio_attr>> | Set Radio Carrier Attributes | <- | Received
| 0x45 | Set Radio Carrier Attributes Ack | -> | Sent
| 0x46 | Set Radio Carrier Attributes Nack | -> | Sent
.3+.| 8.6.3 | 0x47 .3+.| <<set_chan_attr>> | Set Channel Attributes | <- | Received
| 0x48 | Set Channel Attributes Ack | -> | Sent
| 0x49 | Set Channel Attributes Nack | -> | Sent
6+<| *State Management and Event Report Messages:*
| 8.8.1 | 0x61 | <<state_changed_rep>> | State Changed Event Report | -> | Sent
.3+.| 8.8.5 | 0x69 .3+.| <<chg_adm_state>> | Change Administrative State | <- | Received
| 0x6A | Change Administrative State Ack | -> | Sent
| 0x6B | Change Administrative State Nack | -> | Sent
6+<| *Equipment Management Messages:*
.3+.| 8.9.2 | 0x74 .3+.| <<opstart>> | Opstart | <- | Received
| 0x75 | Opstart Ack | -> | Sent
| 0x76 | Opstart Nack | -> | Sent
|===
==== Messages Specific to OsmoBTS
.Messages specific to OsmoBTS, not found in 3GPP TS 12.21
[options="header"]
[options="header",cols="20%,55%,5%,20%"]
|===
| This document § | Message | <-/-> | Received/Sent by OsmoBTS
| <<ipacc_set_attr>> | Set Attribute | <- | Received
|===
==== Messages Not Implemented by OsmoBTS
.3GPP TS 12.21 messages not implemented by OsmoBTS
[options="header",cols="10%,10%,80%"]
|===
| TS 12.21 § | type code (hex) | Message
3+<| *SW Download Management Messages:*
.3+.| 8.3.1 | 0x01 | Load Data Initiate
| 0x02 | Load Data Initiate Ack
| 0x03 | Load Data Initiate Nack
.2+.| 8.3.2 | 0x04 | Load Data Segment
| 0x05 | Load Data Segment Ack
| 8.3.3 | 0x06 | Load Data Abort
.3+.| 8.3.4 | 0x07 | Load Data End
| 0x08 | Load Data End Ack
| 0x09 | Load Data End Nack
.3+.| 8.3.5 | 0x0A | SW Activate Request
| 0x0B | SW Activate Request Ack
| 0x0C | SW Activate Request Nack
.3+.| 8.3.6 | 0x0D | Activate SW
| 0x0E | Activate SW Ack
| 0x0F | Activate SW Nack
3+<| *A-bis Interface Management Messages:*
.3+.| 8.4.1 | 0x21 | Establish TEI
| 0x22 | Establish TEI Ack
| 0x23 | Establish TEI Nack
.3+.| 8.4.2 | 0x24 | Connect Terrestrial Signalling
| 0x25 | Connect Terrestrial Signalling Ack
| 0x26 | Connect Terrestrial Signalling Nack
.3+.| 8.4.3 | 0x27 | Disconnect Terrestrial Signalling
| 0x28 | Disconnect Terrestrial Signalling Ack
| 0x29 | Disconnect Terrestrial Signalling Nack
.3+.| 8.4.4 | 0x2A | Connect Terrestrial Traffic
| 0x2B | Connect Terrestrial Traffic Ack
| 0x2C | Connect Terrestrial Traffic Nack
.3+.| 8.4.5 | 0x2D | Disconnect Terrestrial Traffic
| 0x2E | Disconnect Terrestrial Traffic Ack
| 0x2F | Disconnect Terrestrial Traffic Nack
3+<| *Transmission Management Messages:*
.3+.| 8.5.1 | 0x31 | Connect Multi-Drop Link
| 0x32 | Connect Multi-Drop Link Ack
| 0x33 | Connect Multi-Drop Link Nack
.3+.| 8.5.2 | 0x34 | Disconnect Multi-Drop Link
| 0x35 | Disconnect Multi-Drop Link Ack
| 0x36 | Disconnect Multi-Drop Link Nack
3+<| *Test Management Messages:*
.3+.| 8.7.1 | 0x51 | Perform Test
| 0x52 | Perform Test Ack
| 0x53 | Perform Test Nack
.3+.| 8.7.2 | 0x54 | Test Report
| 0x55 | Send Test Report
| 0x56 | Send Test Report Ack
| 8.7.3 | 0x57 | Send Test Report Nack
.3+.| 8.7.4 | 0x58 | Stop Test
| 0x59 | Stop Test Ack
| 0x5A | Stop Test Nack
3+<| *State Management and Event Report Messages:*
| 8.8.2 | 0x62 | Failure Event Report
.3+.| 8.8.3 | 0x63 | Stop Sending Event Reports
| 0x64 | Stop Sending Event Reports Ack
| 0x65 | Stop Sending Event Reports Nack
.3+.| 8.8.4 | 0x66 | Restart Sending Event Reports
| 0x67 | Restart Sending Event Reports Ack
| 0x68 | Restart Sending Event Reports Nack
.3+.| 8.8.6 | 0x6C | Change Administrative State Request
| 0x6D | Change Administrative State Request Ack
| 0x6E | Change Administrative State Request Nack
.3+.| 8.8.7 | 0x93 | Report Outstanding Alarms
| 0x94 | Report Outstanding Alarms Ack
| 0x95 | Report Outstanding Alarms Nack
3+<| *Equipment Management Messages:*
.3+.| 8.9.1 | 0x71 | Changeover
| 0x72 | Changeover Ack
| 0x73 | Changeover Nack
.3+.| 8.9.3 | 0x87 | Reinitialize
| 0x88 | Reinitialize Ack
| 0x89 | Reinitialize Nack
.3+.| 8.9.4 | 0x77 | Set Site Outputs
| 0x78 | Set Site Outputs Ack
| 0x79 | Set Site Outputs Nack
.3+.| 8.9.5 | 0x90 | Change HW Configuration
| 0x91 | Change HW Configuration Ack
| 0x92 | Change HW Configuration Nack
3+<| *Measurement Management Messages:*
| 8.10.1 | 0x8A | Measurement Result Request
| 8.10.2 | 0x8B | Measurement Result Response
| 8.10.3 | 0x8C | Stop Measurement
| 8.10.4 | 0x8D | Start Measurement
3+<| *Other Messages:*
| 8.11.1 | 0x81 | Get Attributes
| 8.11.3 | 0x82 | Get Attribute(s) Response
| 8.11.1 | 0x83 | Get Attributes Nack
.3+.| 8.11.2 | 0x84 | Set Alarm Threshold
| 0x85 | Set Alarm Threshold Ack
| 0x86 | Set Alarm Threshold Nack
|===
=== Details on Compliant OML Messages
[[sw_act_rep]]
==== SW Activated Report
OsmoBTS will send an _SW Activated Report_ when RF has been activated
successfully. The message is compliant with 3GPP TS 12.21 § 8.3.7.
Upon RF activation, two _SW Activated Report_ messages will be sent, for the Object Classes
- Radio Carrier (0x02)
- Baseband Transceiver (0x04)
[[set_bts_attr]]
==== Set BTS Attributes
OsmoBTS will receive a _Set BTS Attributes_ message and reply with a
corresponding ACK message on success. IE handling is fully compliant to TS
12.21, except that a change of BCCH ARFCN or BSIC while in operation is not
supported, and hence the _Starting Time_ IE is rejected.
._Set BTS Attributes_ IEs not handled by OsmoBTS
[options="header",cols="10%,30%,60%"]
|===
| TS 12.21 § | IE Name | Handling
| 9.4.52 | Starting Time | not supported (provokes NACK cause 0x10)
|===
[[set_radio_attr]]
==== Set Radio Carrier Attributes
This message conforms to 3GPP TS 12.21, with the following limitation,
as frequency hopping is not supported by OsmoBTS:
._Set Radio Carrier Attributes_ IE limitations
[options="header",cols="10%,30%,60%"]
|===
| TS 12.21 § | IE Name | Handling
| 9.4.5 | ARFCN List | ignored
|===
[[set_chan_attr]]
==== Set Channel Attributes
This message conforms to 3GPP TS 12.21, with the following limitation: OpenBTS
does not support frequency hopping, and the following 3GPP TS 12.21 IEs provoke
a NACK response when sent to OsmoBTS, as frequency hopping is not
supported:
._Set Channel Attributes_ IE limitations
[options="header",cols="10%,30%,60%"]
|===
| TS 12.21 § | IE Name | Handling
| 9.4.21 | HSN | not supported (provokes NACK cause 0x10)
| 9.4.27 | MAIO | not supported (provokes NACK cause 0x10)
| 9.4.52 | Starting Time | not supported (provokes NACK cause 0x10)
|===
[[state_changed_rep]]
==== State Changed Event Report
This message is compliant with 3GPP TS 12.21. Exactly these IEs are sent by
OsmoBTS:
[options="header"]
[cols="30%,25%,15%,15%,15%"]
|===
| INFORMATION ELEMENT | REFERENCE | PRESENCE | FORMAT | LENGTH
| Message Type (0xf5) | 3GPP TS 12.21 9.1 | M | V | 1
| Object Class | 3GPP TS 12.21 9.2 | M | V | 1
| Object Instance | 3GPP TS 12.21 9.3 | M | V | 3
| Operational State | 3GPP TS 12.21 9.4.38 | O | TV | 2
| Availability Status | 3GPP TS 12.21 9.4.7 | O | TL16V (with length of 1) | 3
|===
[[chg_adm_state]]
==== Change Administrative State
This message is compliant with 3GPP TS 12.21 § 8.8.5. It applies to all of the
Objects Classes defined in 3GPP TS 12.21 § 9.2 as well as
<<addnl_obj_classes>>.
[[opstart]]
==== Opstart
This message is compliant with 3GPP TS 12.21 § 8.9.2. It applies to all of the
Objects Classes defined in 3GPP TS 12.21 § 9.2 as well as
<<addnl_obj_classes>>.
=== Details on OsmoBTS Specific Messages
[[ipacc_set_attr]]
==== Set Attribute
The message type is 0xf5. This message is sent to OsmoBTS to set
attributes on instances of managed objects of the non-standard
additional Object Classes (see <<addnl_obj_classes>>).
The message specifics depend on the Object Class and are detailed in
<<addnl_obj_classes>>.
[options="header"]
[cols="30%,25%,15%,15%,15%"]
|===
| INFORMATION ELEMENT | REFERENCE | PRESENCE | FORMAT | LENGTH
| Message Type (0xf5) | 3GPP TS 12.21 9.1 | M | V | 1
| Object Class | 3GPP TS 12.21 9.2 | M | V | 1
| Object Instance | 3GPP TS 12.21 9.3 | M | V | 3
5+<| _Object Class specific IEs follow, see <<addnl_obj_classes>>..._
|===
[[addnl_obj_classes]]
=== Additional Object Classes
In addition to 3GPP TS 12.21 Chapter 9.2, the following managed objects
are supported:
.Additional Managed Object Classes
[options="header"]
[cols="20%,20%,60%"]
|===
| Value | Name | Description
| 0xf0 | GPRS NSE | GPRS-NS Entity
| 0xf1 | GPRS CELL | GPRS Cell Entity
| 0xf2 | GPRS NSVC | GPRS NS Virtual Circuit
|===
==== GPRS-NSE Managed Object
There is one NS Entity per BTS. It supports the *Set Attribute* message
with the following Information Elements:
[options="header"]
[cols="30%,25%,15%,15%,15%"]
|===
| INFORMATION ELEMENT | REFERENCE | PRESENCE | FORMAT | LENGTH
| Message Type | 3GPP TS 12.21 9.1 | M | V | 1
| Object Class | 3GPP TS 12.21 9.2 | M | V | 1
| Object Instance | 3GPP TS 12.21 9.3 | M | V | 3
| GPRS NSEI | <<NM_ATT_IPACC_NSEI>> | O | TL16V | >= 5
| GPRS NS Configuration | <<NM_ATT_IPACC_NS_LINK_CFG>> | O | TL16V | >= 10
| GPRS BSSGP Configuration | <<NM_ATT_IPACC_BSSGP_CFG>> | O | TL16V | >= 14
|===
==== GPRS Cell Managed Object
There is one GPRS Cell entity per BTS. It supports the *Set Attribute*
message with the following Information Elements:
[options="header"]
[cols="30%,25%,15%,15%,15%"]
|===
| INFORMATION ELEMENT | REFERENCE | PRESENCE | FORMAT | LENGTH
| Message Type | 3GPP TS 12.21 9.1 | M | V | 1
| Object Class | 3GPP TS 12.21 9.2 | M | V | 1
| Object Instance | 3GPP TS 12.21 9.3 | M | V | 3
| GPRS Routing Area Code | <<NM_ATT_IPACC_RAC>> | O | TL16V | >= 4
| GPRS Paging Configuration | <<NM_ATT_IPACC_GPRS_PAGING_CFG>> | O | TL16V | >= 5
| GPRS RLC Configuration | <<NM_ATT_IPACC_RLC_CFG>> | O | TL16V | >= 12
| GPRS Coding Schemes | <<NM_ATT_IPACC_CODING_SCHEMES>> | O | TL16V | >= 5
| GPRS RLC Configuration 2 | <<NM_ATT_IPACC_RLC_CFG_2>> | O | TL16V | >= 8
| GPRS RLC Configuration 3 | <<NM_ATT_IPACC_RLC_CFG_3>> | O | TL16V | >= 4
|===
==== GPRS NS-VC Managed Object
There are two GPRS NS-VC instances per BTS. It supports the *Set
Attribute* message with the following Information Elements:
[options="header"]
[cols="30%,25%,15%,15%,15%"]
|===
| INFORMATION ELEMENT | REFERENCE | PRESENCE | FORMAT | LENGTH
| Message Type | 3GPP TS 12.21 9.1 | M | V | 1
| Object Class | 3GPP TS 12.21 9.2 | M | V | 1
| Object Instance | 3GPP TS 12.21 9.3 | M | V | 3
| GPRS NSVCI | <<NM_ATT_IPACC_NSVCI>> | O | TL16V | >= 5
| GPRS NS Link Configuration | <<NM_ATT_IPACC_NS_LINK_CFG>> | O | TL16V | >= 11
|===
=== Information Elements Overview
All of the IEs handled by OsmoBTS are listed below, with limitations and
additions to TS 12.21 specified in more detail.
==== IEs Conforming to TS 12.21
The following Information Elements are accepted by OsmoBTS. Not all IEs are
actually evaluated.
.IEs conforming to TS 12.21
[options="header",cols="5%,10%,40%,5%,40%"]
|===
| tag (hex) | TS 12.21 § | IE name | <-/-> | Received/Sent by OsmoBTS
| 0x00 | 9.4.1 | Abis Channel | | _ignored_
| 0x01 | 9.4.2 | Additional Info | | _ignored_
| 0x02 | 9.4.3 | Additional Text | | _ignored_
| 0x03 | 9.4.4 | Administrative State | <- -> | Received & Sent
| 0x04 | 9.4.5 | ARFCN List | <- | Received, with exactly 1 ARFCN: see <<NM_ATT_ARFCN_LIST>>;
ignored by _Set Radio Attribute_ message (<<set_radio_attr>>)
| 0x05 | 9.4.6 | Autonomously Report | | _ignored_
| 0x06 | 9.4.7 | Availability Status | -> | Sent
| 0x07 | 9.4.8 | BCCH ARFCN | <- | Received
| 0x08 | 9.4.9 | BSIC | <- | Received
| 0x09 | 9.4.10 | BTS Air Timer | <- | Received
| 0x0a | 9.4.11 | CCCH Load Indication Period | <- | Received
| 0x0b | 9.4.12 | CCCH Load Threshold | <- | Received
| 0x0c | 9.4.13 | Channel Combination | <- | Received, with additional channel combinations: see <<ie_chan_comb>>
| 0x0d | 9.4.14 | Connection Failure Criterion | <- | Received, with limitations see <<ie_conn_fail_crit>>
| 0x0e | 9.4.15 | Destination | | _ignored_
| 0x0f | 9.4.16 | Event Type | | _ignored_
| 0x11 | 9.4.17 | File Data | | _ignored_
| 0x12 | 9.4.18 | File Id | | _ignored_
| 0x13 | 9.4.19 | File Version | | _ignored_
| 0x14 | 9.4.20 | GSM Time | | _ignored_
| 0x16 | 9.4.22 | HW Configuration | | _ignored_
| 0x18 | 9.4.24 | Intave Parameter | <- | _ignored_
| 0x19 | 9.4.25 | Interference level Boundaries | <- | _ignored_
| 0x1a | 9.4.26 | List of Required Attributes | | _ignored_
| 0x1c | 9.4.28 | Manufacturer Dependent State | | _ignored_
| 0x1d | 9.4.29 | Manufacturer Dependent Thresholds | | _ignored_
| 0x1e | 9.4.30 | Manufacturer Id | | _ignored_
| 0x1f | 9.4.31 | Max Timing Advance | <- | Received
| 0x20 | 9.4.34 | Multi-drop BSC Link | | _ignored_
| 0x21 | 9.4.35 | Multi-drop next BTS Link | | _ignored_
| 0x22 | 9.4.36 | Nack Causes | -> | Sent
| 0x23 | 9.4.37 | Ny1 | <- | Received
| 0x24 | 9.4.38 | Operational State | -> | Sent
| 0x25 | 9.4.39 | Overload Period | <- | _ignored_
| 0x26 | 9.4.40 | Physical Config | | _ignored_
| 0x27 | 9.4.41 | Power Class | | _ignored_
| 0x28 | 9.4.42 | Power Output Thresholds | | _ignored_
| 0x29 | 9.4.43 | Probable Cause | | _ignored_
| 0x2a | 9.4.44 | RACH Busy Threshold | <- | Received
| 0x2b | 9.4.45 | RACH Load Averaging Slots | <- | _ignored_
| 0x2c | 9.4.46 | Radio Sub Channel | | _ignored_
| 0x2d | 9.4.47 | RF Max Power Reduction | <- | Received
| 0x2e | 9.4.48 | Site Inputs | | _ignored_
| 0x2f | 9.4.49 | Site Outputs | | _ignored_
| 0x30 | 9.4.50 | Source | | _ignored_
| 0x31 | 9.4.51 | Specific Problems | | _ignored_
| 0x33 | 9.4.53 | T200 | <- | _ignored_ (1s on DCCH, 2s on ACCH)
| 0x34 | 9.4.54 | TEI | | _ignored_
| 0x35 | 9.4.55 | Test Duration | | _ignored_
| 0x36 | 9.4.56 | Test No | | _ignored_
| 0x37 | 9.4.57 | Test Report Info | | _ignored_
| 0x38 | 9.4.58 | VSWR Thresholds | | _ignored_
| 0x39 | 9.4.59 | Window Size | | _ignored_
| 0x40 | 9.4.60 | TSC | <- | Received, with limitations: see <<NM_ATT_TSC>>
| 0x41 | 9.4.61 | SW Configuration | | _ignored_
| 0x43 | 9.4.63 | Perceived Severity | | _ignored_
| 0x44 | 9.4.64 | Get Attribute Response Info | | _ignored_
| 0x45 | 9.4.65 | Outstanding Alarm Sequence | | _ignored_
| 0x46 | 9.4.66 | HW Conf Change Info | | _ignored_
| 0x47 | 9.4.32 | Measurement Result | | _ignored_
|===
==== IEs Not Conforming to TS 12.21
.IEs not conforming to TS 12.21
[options="header",cols="5%,10%,30%,55%"]
|===
| tag (hex) | TS 12.21 § | IE name | Description
| 0x15 | 9.4.21 | HSN | presence causes NACK response
| 0x17 | 9.4.23 | HW Description | _ignored_ by OsmoBTS, but coding may differ, see <<ie_hw_desc>>
| 0x1b | 9.4.27 | MAIO | presence causes NACK response
| 0x32 | 9.4.52 | Starting Time | presence causes NACK response
| 0x42 | 9.4.62 | SW Description | not supported
| 0x48 | 9.4.33 | Measurement Type | not supported
|===
==== Additional Attributes and Parameters
The following Information Elements are defined in addition to those
specified in 3GPP TS 12.21 Chapter 9.4.
All of these additional IEs are _received_ by OsmoBTS.
The content of these attributes is not used by OsmoBTS, but
simply passed to OsmoPCU connected to the PCU socket.
.Additional IEs handled by OsmoBTS but not defined in TS 12.21
[options="header",cols="5%,50%,45%"]
|===
| tag (hex) | IE name | Description
| 0x80 | RSL Destination IP Address | <<NM_ATT_IPACC_DST_IP>>
| 0x81 | RSL Destination TCP Port | <<NM_ATT_IPACC_DST_IP_PORT>>
| 0x85 | RSL IPA Stream ID | <<NM_ATT_IPACC_STREAM_ID>>
| 0x9a | GPRS Routing Area Code | <<NM_ATT_IPACC_RAC>>
| 0x9c | GPRS Paging Configuration | <<NM_ATT_IPACC_GPRS_PAGING_CFG>>
| 0x9d | GPRS NSEI | <<NM_ATT_IPACC_NSEI>>
| 0x9e | GPRS BVCI | <<NM_ATT_IPACC_BVCI>>
| 0x9f | GPRS NSVCI | <<NM_ATT_IPACC_NSVCI>>
| 0xa0 | GPRS NS Configuration | <<NM_ATT_IPACC_NS_CFG>>
| 0xa1 | GPRS BSSGP Configuration | <<NM_ATT_IPACC_BSSGP_CFG>>
| 0xa2 | GPRS NS Link Configuration | <<NM_ATT_IPACC_NS_LINK_CFG>>
| 0xa3 | GPRS RLC Configuration | <<NM_ATT_IPACC_RLC_CFG>>
| 0xa8 | GPRS Coding Schemes | <<NM_ATT_IPACC_CODING_SCHEMES>>
| 0xa9 | GPRS RLC Configuration 2 | <<NM_ATT_IPACC_RLC_CFG_2>>
| 0xac | GPRS RLC Configuration 3 | <<NM_ATT_IPACC_RLC_CFG_3>>
|===
=== Details on IEs
[[ie_hw_desc]]
==== HW Description
TS 12.21 suggests a series of 5 length-value pairs for the _HW Description_ IE.
Instead, OsmoBTS interprets it as a single TL16V. The value of this IE is
ignored by OsmoBTS, yet the coding may affect message parsing.
[width="40%",cols="90%,10%"]
[grid="none"]
|===
| Attribute Identifier (0x17) | 1
| Length | 2-3
| Ignored | N
|===
[[NM_ATT_ARFCN_LIST]]
==== ARFCN List
Since OsmoBTS does not support frequency hopping, the _ARFCN List_ must contain
exactly one ARFCN.
[[ie_chan_comb]]
==== Additional Channel Combinations
In addition to 3GPP TS 12.21 Chapter 9.4.13, the following channel
combinations are supported:
.Additional Channel Combinations
[options="header"]
[cols="10%,90%"]
|===
| Value | Description
| 0x0b | Reserved for PBCCH + PCCCH + PDTCH/F + PACCH/F + PTCCH/F
| 0x0c | Reserved for PBCCH + PDTCH/F + PACCH/F + PTCCH/F
| 0x0d | PDTCH/F + PACCH/F + PTCCH/F
| 0x80 | Reserved for Dynamic TCH/F / PDCH
| 0x81 | Reserved for Dynamic TCH/F / TCH/H
|===
[[ie_conn_fail_crit]]
==== Connection Fail Criterion
3GPP TS 12.21 Chapter 9.4.14 specifies two different options for the
_Connection Failure Criterion_. OsmoBTS only implements the option
coded as 0x01, i.e. based upon uplink SACCH error rate
(RADIO_LINK_TIMEOUT).
[[NM_ATT_TSC]]
==== TSC
Due to limitations in the currently supported PHY implementations,
OsmoBTS supports only one global TSC for all channels on one TRX, rather
than a separate TSC for each timeslot, as expected by 3GPP TS 12.21.
[[NM_ATT_IPACC_DST_IP]]
==== RSL Destination IP Address
The value part of this attribute has a length of 4 octets and is encoded
as IPv4 address in network byte order.
[width="40%",cols="90%,10%"]
[grid="none"]
|===
| Attribute Identifier (0x80) | 1
| IPv4 Address (MSB first) | 2-5
|===
[[NM_ATT_IPACC_DST_IP_PORT]]
==== RSL Destination TCP Port
The value part of this attribute has a length of 2 octets and contains
the TCP destination port for the RSL connection, encoded in network byte
order.
[width="40%",cols="90%,10%"]
[grid="none"]
|===
| Attribute Identifier (0x81) | 1
| Port number (MSB first) | 2-3
|===
[[NM_ATT_IPACC_STREAM_ID]]
==== RSL IPA Stream ID
The value part of this attribute has a length of one octet and specifies
the IPA stream ID to be used for the RSL connection of this TRX.
[width="40%",cols="90%,10%"]
[grid="none"]
|===
| Attribute Identifier (0x85) | 1
| Stream ID | 2
|===
[[NM_ATT_IPACC_RAC]]
==== GPRS Routing Area Code
The value part of the GPRS Routing Area code consist of a single octet
encoding the GPRS Routing Area Code.
The content of this attribute is not used by OsmoBTS, but
simply passed to OsmoPCU connected to the PCU socket.
[[NM_ATT_IPACC_GPRS_PAGING_CFG]]
==== GPRS Paging Configuration
The value part of this attribute consists of two octets encoded as
follows:
[options="header"]
[cols="10%,90%"]
|===
| Offset | Description
| 0 | GPRS Paging repeat time in units of 50ms intervals
| 1 | GPRS Paging repeat count
|===
[[NM_ATT_IPACC_NSEI]]
==== GPRS NSEI
The value part of the GPRS NSEI is encoded as 16bit integer value in
network byte order.
The content of this attribute is not used by OsmoBTS, but
simply passed to OsmoPCU connected to the PCU socket.
[[NM_ATT_IPACC_BVCI]]
==== GPRS BVCI
The value part of this attribute consists of two octets encoding the
BSSGP Virtual Circuit Identifier (BVCI) as unsigned 16 bit integer in
network byte order.
[[NM_ATT_IPACC_NSVCI]]
==== GPRS NSVCI
The value part of the GPRS NSVCI attribute is a 16bit unsigned integer
in network byte order, encoding the GPRS NSVCI as specified in 3GPP TS
08.16.
The content of this attribute is not used by OsmoBTS, but
simply passed to OsmoPCU connected to the PCU socket.
[[NM_ATT_IPACC_NS_CFG]]
==== GPRS NS Configuration
The value part of the GPRS NS Configuration consist of an array of 7 octets, each
describing one GPRS NS related timer:
The content of this attribute is not used by OsmoBTS, but
simply passed to OsmoPCU connected to the PCU socket.
[[NM_ATT_IPACC_BSSGP_CFG]]
==== GPRS BSSGP Configuration
The value part of the GPRS BSSGP configuration consists of an array of
11 octets, each describing one GPRS BSSGP related timer:
[options="header"]
[cols="10%,90%"]
|===
| Offset | Description
| 0 | Blocking Timer (T1)
| 1 | Blocking Retries
| 2 | Unblocking Retries
| 3 | Reset Timer (T2)
| 4 | Reset Retries
| 5 | Suspend Timer (T3) in units of 100ms
| 6 | Suspend Retries
| 7 | Resume Timer (T4) in units of 100ms
| 8 | Resume Retries
| 9 | Capability Update Timer (T5)
| 10 | Capability Update Retries
|===
The detailed description of the meaning of those timers is given in the
GPRS BSSGP specification 3GPP TS 08.18.
The content of this attribute is not used by OsmoBTS, but
simply passed to OsmoPCU connected to the PCU socket.
[[NM_ATT_IPACC_NS_LINK_CFG]]
==== GPRS NS Link Configuration
The content of this attribute is 8 octets long and encoded as follows:
[options="header"]
[cols="10%,10%,80%"]
|===
| Offset | Length | Description
| 0 | 2 | GPRS-NS Remote UDP Port Number (SGSN side)
| 2 | 4 | GPRS-NS Remote IPv4 Address (SGSN side)
| 6 | 2 | GPRS-NS Local UDP Port Number (BTS side)
|===
All values are encoded in network byte order.
The content of this attribute is not used by OsmoBTS, but
simply passed to OsmoPCU connected to the PCU socket.
[[NM_ATT_IPACC_RLC_CFG]]
==== GPRS RLC Configuration
The value part of the GPRS RLC Configuration consists of an array of 9
octets, each describing a RLC timer:
[options="header"]
[width="60%",cols="10%,80%,10%"]
|===
| Offset | Description | Unit
| 0 | GPRS RLC Timer T3142 | s
| 1 | GPRS RLC Timer T3169 | s
| 2 | GPRS RLC Timer T3191 | s
| 3 | GPRS RLC Timer T3193 | 10ms
| 4 | GPRS RLC Timer T3195 | s
| 5 | GPRS RLC Timer T3101 | s
| 6 | GPRS RLC Timer T3103 | s
| 7 | GPRS RLC Timer T3105 | s
| 8 | GPRS RLC CV Countdown | -
|===
The meaning of the RLC timers are specified in 3GPP TS 04.60.
The countdown value specifies the RLC CV value from which the countdown
procedure is started.
The content of this attribute is not used by OsmoBTS, but
simply passed to OsmoPCU connected to the PCU socket.
[[NM_ATT_IPACC_CODING_SCHEMES]]
==== GPRS Coding Schemes
The value part of the GPRS Coding Schemes consists of two octets
encoding the available GPRS and EDGE coding schemes.
[options="header"]
|===
| *bit* | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0
| byte at offset 0 | MCS9 | x | x | x | CS4 | CS3 | CS2 | CS1
| byte at offset 1 | MCS8 | MCS7| MCS6 | MCS5 | MCS4| MCS3 | MCS2 | MCS1
|===
The content of this attribute is not used by OsmoBTS, but
simply passed to OsmoPCU connected to the PCU socket.
[[NM_ATT_IPACC_RLC_CFG_2]]
==== GPRS RLC Configuration 2
The value part of this attribute is 8 octets long and encoded as
follows:
[options="header"]
[width="60%",cols="10%,10%,70%,10%"]
|===
| Offset | Length | Description | Unit
| 0 | 2 | Downlink TBF Extension Timer | 10ms
| 2 | 2 | Uplink TBF Extension Timer | 10ms
| 4 | 2 | Initial GPRS Coding Scheme | -
|===
The Initial GPRS Coding Scheme is encoded as follows:
[options="header"]
[width="40%",cols="50%,50%"]
|===
| Value | Description
| 1 | CS 1
| 2 | CS 2
| 3 | CS 3
| 4 | CS 4
|===
The content of this attribute is not used by OsmoBTS, but
simply passed to OsmoPCU connected to the PCU socket.
[[NM_ATT_IPACC_RLC_CFG_3]]
==== GPRS RLC Configuration 3
The content of this attribute contains information about the initial MCS
used for new EDGE TBFs.
It is encoded as follows:
[options="header"]
[width="40%",cols="50%,50%"]
|===
| Value | Description
| 1 | MCS 1
| 2 | MCS 2
| 3 | MCS 3
| 4 | MCS 4
| 5 | MCS 5
| 6 | MCS 6
| 7 | MCS 7
| 8 | MCS 8
| 9 | MCS 9
|===
The content of this attribute is not used by OsmoBTS, but
simply passed to OsmoPCU connected to the PCU socket.
=== A-bis OML Initialization / BTS bring-up
At the time an Abis/IP BTS connects to via OML to the BSC, it is
initialized according to the procedures described in 3GPP TS 12.21 as
amended in this document.
Each Managed Object (MO) is separately initialized. The initialization
sequence and parameters differ slightly depending on the MO involved.
Some parts of the sequences described below are optional, such as the
Software activation. In the OsmoBTS case, the software is nod modular
and thus all MOs start with the software fully activated. Thus, no
__Software Activate Request__ is being sent by the MO to the BSC, nor
does the BSC need to initialize the __Activate Software__ procedure.
Still, the full sequences are shown in order to explain the Abis/IP
protocol.
Also, the initial state of the MOs at time of OML connection
initialization is not always guaranteed to be Disabled/Notinstalled.
Rather, the BSC implementation has to deal with the initial state as
reported by the MOs at time of re-connection.
==== Site Manager MO Initialization
.A-bis OML Initialization of Site Manager MO
["mscgen"]
----
include::oml-mo-sitemgr.msc[]
----
As the Site Manager MO does not depend on other MOs, nor does it have an
Administrative state (__Locked/Unlocked__), it immediately ends up in the
__Enabled__ state.
==== BTS MO Initialization
.A-bis OML Initialization of BTS MO
["mscgen"]
----
include::oml-mo-bts.msc[]
----
As can be seen in the BTS MO, its state is
* Availability state __Dependency__, meaning it depends on other MOs to
be initialized before becoming enabled.
* Administrative state __Locked__, as the object is first waiting to
receive attributes in the __Locked__ state, before the __Change
Administrative State (Unlocked)__ procedure is used to request
transitioning into Unlocked state.
==== Baseband Transceiver MO Initialization
.A-bis OML Initialization of Baseband Transceiver MO
["mscgen"]
----
include::oml-mo-transceiver.msc[]
----
There is one Baseband Transceiver MO per TRX in the BTS. For a
multi-TRX BTS, the above procedure must be repeated for each TRX.
==== Radio Carrier MO Initialization
.A-bis OML Initialization of Radio Carrier MO
["mscgen"]
----
include::oml-mo-carrier.msc[]
----
There is one Radio Carrier MO per TRX in the BTS. For a multi-TRX BTS,
the above procedure must be repeated for each TRX.
==== Channel MO Initialization
.A-bis OML Initialization of Radio Carrier MO
["mscgen"]
----
include::oml-mo-channel.msc[]
----
There are 8 Timeslots in each TRX, and correspondingly 8 Channel MOs in
every TRX. The above procedure must thus be repeated for each timeslot
in each transceiver of the BTS.
==== Full Initialization of entire BTS
Some of the steps are optional, as is their detailed ordering. In
reality, the procedures for different MOs may overlap. The message
sequence charts in this document have been hand-crafted to avoid such
overlap for the sake of clarity.
[[oml-msc-1]]
.A-bis OML BTS bring-up (1/3)
["mscgen"]
----
include::oml-startup.msc[]
----
As can be seen in <<oml-msc-1>>, after the OML TCP connection is
established
. the identity is exchanged via IPA CCM,
. the BTS sends an 'OML EVENT STATE CHANGED REPORT' for every
Managed Object
. the BTS subsequently requests the activation of its 'Site Manager' Object
which the BSC performs by the 'Activate SW' command.
. After successful activation of the software in the Site Manager,
.. the state changes to 'Enabled', and an event report is generated
accordingly
.. the BSC is notified about the SW activation in an associated report
. Finally, the BSC requests the start of the Site Manager
.. using the 'OPSTART' command,
.. which is subsequently acknowledged by the Site Manager.
[[oml-msc-2]]
.A-bis OML BTS bring-up (2/3)
["mscgen"]
----
include::oml-startup2.msc[]
----
[[oml-msc-3]]
.A-bis OML BTS bring-up (3/3)
["mscgen"]
----
include::oml-startup3.msc[]
----
In <<oml-msc-2>>, we can see
. Software Activation and associated state transitions of the BTS MO
. Setting of the BTS Attributes followed by OPSTART
. Software Activation and associated state transitions of the 'Baseband
Transceiver' MO
. Software Activation and associated state transitions of the 'Radio
Carrier' MO
. Once the 'Baseband Transceiver' MO has its software activated, the
'Channel' MOs (one for each timeslot) indicate their state change and
software activation, too.
In <<oml-msc-3>>, we can see
. The 'Radio Carrier' MO Software Activation
. The Request to the 'Baseband Transceiver' MO to establish the RSL
signalling connection to the BSC.
. Subsequent OPSTART and Change of Administrative State on the 'Baseband
Transceiver' MO
. The following procedure for each of the 'Channel' MOs:
.. Setting the Channel Attributes (such as channel combination)
.. OPSTART
.. Changing the Administrative State to Unlocked
.. Subsequent State Change Event Report with the new state
. After all 'Channel' MOs are initialized, the Radio Carrier goes through
a similar procedure of
.. Setting its attributes
.. OPSTART
.. Changing its Administrative State to Unlocked
.. Subsequent State Change Event Report with the new State (Enabled/OK)
. All 'Channel' MOs now also report their state as Enabled/OK
. Finally, the BTS reports its state as Enabled/OK

22
doc/manuals/abis/rsl-startup-pri.msc Normal file
View File

@ -0,0 +1,22 @@
msc {
bts [label="TRX"], bsc [label="BSC"];
bts => bsc [label="TCP Connect (Port 3003, RSL)"];
bts box bsc [label="IPA CCM Identification (Port 3003)"];
|||;
bts <= bsc [label="BCCH Information (SI1)"];
bts <= bsc [label="BCCH Information (SI2)"];
...;
bts <= bsc [label="BCCH Information (SI3)"];
bts <= bsc [label="BCCH Information (SI4)"];
|||;
bts <= bsc [label="SACCH FILLING (SI5)"];
...;
bts <= bsc [label="SACCH FILLING (SI6)"];
|||;
bts => bsc [label="RF Resource Indication"];
...;
bts => bsc [label="RF Resource Indication"];
...;
}

16
doc/manuals/abis/rsl-startup-sec.msc Normal file
View File

@ -0,0 +1,16 @@
msc {
bts [label="TRX"], bsc [label="BSC"];
bts => bsc [label="TCP Connect (Port 3003, RSL)"];
bts box bsc [label="IPA CCM Identification (Port 3003)"];
|||;
bts <= bsc [label="SACCH FILLING (SI5)"];
...;
bts <= bsc [label="SACCH FILLING (SI6)"];
|||;
bts => bsc [label="RF Resource Indication"];
...;
bts => bsc [label="RF Resource Indication"];
...;
}

56
doc/manuals/abis/rsl-tch-rtp.msc Normal file
View File

@ -0,0 +1,56 @@
msc {
hscale = 2;
ms [label="MS"], bts [label="BTS"], bsc [label="BSC"], Msc [label="MSC"], mgw [label="MGW"];
ms => bts [label="L1 RACH burst"];
bts => bsc [label="RSL CHAN RQD"];
bts <= bsc [label="RSL CHAN ACT"];
bts => bsc [label="RSL CHAN ACT ACK"];
bts <= bsc [label="RSL IMM ASS CMD (RR IMM ASS)"];
ms <= bts [label="RR IMMEDIATE ASSIGN"];
ms => bts [label="LAPDm SABM (CM SERVICE REQ)"];
ms <= bts [label="LAPDm FIXME"];
bts => bsc [label="RSL ESTABLISH IND (CM SERVICE REQ)"];
bsc => Msc [label="CR (BSSAP COMPLETE L3 (CM SERVICE REQ))"];
...;
ms box Msc [label="MM Common Procedures (INFO, ID, AUTH, CIPH)"];
...;
ms => bts [label="CC SETUP"];
bts => bsc [label="RSL DATA IND (CC SETUP)"];
bsc => Msc [label="DT1 (DTAP (CC SETUP))"];
...;
ms box Msc [label="CC Signalling"];
...;
bsc <= Msc [label="BSSAP ASSIGNMENT CMD (TCH)"];
bts <= bsc [label="RSL IPA CRCX", id="1"];
bts => bsc [label="RSL IPA CRCX ACK (IP/Port @ BTS)"];
bsc => Msc [label="FIXME"];
Msc => mgw [label="FIXME"];
bts <- mgw [label="Start RTP + RTCP UDP Flows"];
bts <= bsc [label="RSL DATA REQ (RR CHAN MOD MODIFY)"];
ms <= bts [label="RR CHAN MOD MODIFY"];
ms => bts [label="RR CHAN MOD MODIFY ACK"];
bts => bsc [label="RSL DATA IND (RR CHAN MOD MODIFY ACK)"];
|||;
bts <= bsc [label="RSL MODE MODIFY REQ"];
bts => bsc [label="RSL MODE MODIFY ACK"];
Msc <= mgw [label="FIXME"];
bsc <= Msc [label="FIXME"];
bts <= bsc [label="RSL IPA MDCX (IP/Port @ MGW)", id="2"];
bts => bsc [label="RSL IPA MDCX ACK"];
bts -> mgw [label="Start RTP + RTCP UDP Flows"];
ms box mgw [label="Active Voice Call"];
bts => bsc [label="RSL MEAS RES"];
...;
bts <= bsc [label="RSL IPA DLCX"];
bts => bsc [label="RSL IPA DLCX ACK"];
bts -x mgw [label="Stop RTP + RTCP UDP Flows"];
bts <= bsc [label="RSL RF CHAN REL"];
bts => bsc [label="RSL RF CHAN REL ACK"];
}

681
doc/manuals/abis/rsl.adoc Normal file
View File

@ -0,0 +1,681 @@
== Radio Signalling Link (RSL)
=== List of Messages
The following tables list the RSL messages used by OsmoBTS A-bis/IP,
grouped by their level of compliance with 3GPP TS 08.58.
==== Messages Compliant With TS 08.58
Specific limitations apply, see the linked sections.
.Messages compliant with TS 08.58
[options="header",cols="10%,20%,45%,5%,20%"]
|===
| TS 08.58 § | This document § | Message | <-/-> | Received/Sent by OsmoBTS
5+<| *Radio link layer management messages*
| 8.3.1 | - | DATA REQUEST | <- | Received
| 8.3.2 | - | DATA INDICATION | -> | Sent
| 8.3.3 | - | ERROR INDICATION | -> | Sent
| 8.3.4 | - | ESTABLISH REQUEST | <- | Received
| 8.3.5 | - | ESTABLISH CONFIRM | -> | Sent
| 8.3.6 | - | ESTABLISH INDICATION | -> | Sent
| 8.3.7 | - | RELEASE REQUEST | <- | Received
| 8.3.8 | - | RELEASE CONFIRM | -> | Sent
| 8.3.9 | - | RELEASE INDICATION | -> | Sent
| 8.3.10 | - | UNIT DATA REQUEST | <- | Received
| 8.3.11 | - | UNIT DATA INDICATION | -> | Sent
5+<| *DEDICATED CHANNEL MANAGEMENT MESSAGES*
| 8.4.1 | - | CHANNEL ACTIVATION | <- | Received
| 8.4.2 | - | CHANNEL ACTIVATION ACKNOWLEDGE | -> | Sent
| 8.4.3 | - | CHANNEL ACTIVATION NEGATIVE ACKNOWLEDGE | -> | Sent
| 8.4.4 | - | CONNECTION FAILURE INDICATION | -> | Sent
| 8.4.5 | - | DEACTIVATE SACCH | <- | Received
| 8.4.6 | - | ENCRYPTION COMMAND | <- | Received
| 8.4.7 | - | HANDOVER DETECTION | -> | Sent
| 8.4.8 | <<MEASUREMENT_RESULT>> | MEASUREMENT RESULT | -> | Sent
| 8.4.9 | <<MODE_MODIFY>> | MODE MODIFY | <- | Received
| 8.4.10 | - | MODE MODIFY ACKNOWLEDGE | -> | Sent
| 8.4.11 | - | MODE MODIFY NEGATIVE ACKNOWLEDGE | -> | Sent
| 8.4.14 | - | RF CHANNEL RELEASE | <- | Received
| 8.4.15 | <<MS_POWER_CONTROL>> | MS POWER CONTROL | <- | Received
| 8.4.19 | - | RF CHANNEL RELEASE ACKNOWLEDGE | -> | Sent
| 8.4.20 | <<SACCH_INFO_MODIFY>> | SACCH INFO MODIFY | <- | Received
5+<| *COMMON CHANNEL MANAGEMENT MESSAGES*
| 8.5.1 | <<BCCH_INFORMATION>> | BCCH INFORMATION | <- | Received
| 8.5.2 | - | CCCH LOAD INDICATION | -> | Sent
| 8.5.3 | <<CHANNEL_REQUIRED>> | CHANNEL REQUIRED | -> | Sent
| 8.5.5 | <<PAGING_COMMAND>> | PAGING COMMAND | <- | Received
| 8.5.6 | - | IMMEDIATE ASSIGN COMMAND | <- | Received
| 8.5.8 | <<SMS_BROADCAST_COMMAND>> | SMS BROADCAST COMMAND | <- | Received
5+<| *TRX MANAGEMENT MESSAGES*
| 8.6.1 | <<RF_RESOURCE_INDICATION>> | RF RESOURCE INDICATION | -> | Sent
| 8.6.2 | <<SACCH_FILLING>> | SACCH FILLING | <- | Received
| 8.6.4 | - | ERROR REPORT | -> | Sent
|===
==== Messages Specific to OsmoBTS
.Messages specific to OsmoBTS, not found in 3GPP TS 08.58
[options="header",cols="15%,15%,45%,5%,20%"]
|===
2+| This document § | Message | <-/-> | Received/Sent by OsmoBTS
5+<| *User Plane Transport Management* (<<user_plane_txp_mgmt>>)
.3+.| <<rsl_crcx>> | <<rsl_crcx_msg>> | RSL Create Connection (CRCX) | <- | Received
| <<rsl_crcx_msg_ack>> | RSL Create Connection (CRCX) ACK | -> | Sent
| <<rsl_crcx_msg_nack>> | RSL Create Connection (CRCX) NACK | -> | Sent
.3+.| <<rsl_mdcx>> | <<rsl_mdcx_msg>> | RSL Modify Connection (MDCX) | <- | Received
| <<rsl_mdcx_msg_ack>> | RSL Modify Connection (MDCX) ACK | -> | Sent
| <<rsl_mdcx_msg_nack>> | RSL Modify Connection (MDCX) NACK | -> | Sent
.3+.| <<rsl_dlcx>> | <<rsl_dlcx_msg>> | RSL Delete Connection (DLCX) | <- | Received
| <<rsl_dlcx_msg_ack>> | RSL Delete Connection (DLCX) ACK | -> | Sent
| <<rsl_dlcx_msg_nack>> | RSL Delete Connection (DLCX) NACK | -> | Sent
| <<rsl_dlcx_ind>> | <<rsl_dlcx_ind_msg>> | RSL Delete Connection (DLCX) Indication | -> | Sent
|===
==== Messages Not Implemented by OsmoBTS
.3GPP TS 08.58 messages not implemented by OsmoBTS
[options="header",cols="10%,90%"]
|===
| TS 08.58 § | Message
2+<| *DEDICATED CHANNEL MANAGEMENT MESSAGES*
| 8.4.12 | PHYSICAL CONTEXT REQUEST
| 8.4.13 | PHYSICAL CONTEXT CONFIRM
| 8.4.16 | BS POWER CONTROL
| 8.4.17 | PREPROCESS CONFIGURE
| 8.4.18 | PREPROCESSED MEASUREMENT RESULT
| 8.4.21 | TALKER DETECTION
| 8.4.22 | LISTENER DETECTION
| 8.4.23 | REMOTE CODEC CONFIGURATION REPORT
| 8.4.24 | ROUND TRIP DELAY REPORT
| 8.4.25 | PRE-HANDOVER NOTIFICATION
| 8.4.26 | MULTIRATE CODEC MODIFICATION REQUEST
| 8.4.27 | MULTIRATE CODEC MODIFICATION ACKNOLEWDGE
| 8.4.28 | MULTIRATE CODEC MODIFICATION NEGATIVE ACKNOWLEDGE
| 8.4.29 | MULTIRATE CODEC MODIFICATION PERFORMED
| 8.4.30 | TFO REPORT
| 8.4.31 | TFO MODIFICATION REQUEST
2+<| *COMMON CHANNEL MANAGEMENT MESSAGES*
| 8.5.4 | DELETE INDICATION
| 8.5.7 | SMS BROADCAST REQUEST
| 8.5.9 | CBCH LOAD INDICATION
| 8.5.10 | NOTIFICATION COMMAND
2+<| *TRX MANAGEMENT MESSAGES*
| 8.6.3 | OVERLOAD
2+<| *LOCATION SERVICES MESSAGES*
| 8.7.1 | LOCATION INFORMATION
|===
=== Message Limitation Details
[[MEASUREMENT_RESULT]]
==== Measurement Result
Conforms to 3GPP TS 08.58 § 8.4.8 with this limitation:
._Measuremet Result_ IE limitations
[options="header",cols="10%,30%,60%"]
|===
| TS 08.58 § | IE Name | Handling
| 9.3.37 | MS Timing Offset | never sent by OsmoBTS
|===
[[MODE_MODIFY]]
==== Mode Modify
Conforms to 3GPP TS 08.58 § 8.4.9 with these limitations:
._Mode Modify_ IE limitations
[options="header",cols="10%,30%,60%"]
|===
| TS 08.58 § | IE Name | Handling
| 9.3.45 | Main channel reference | _ignored_
| 9.3.53 | MultiRate Control | _ignored_
| 9.3.54 | Supported Codec Types | _ignored_
|===
[[MS_POWER_CONTROL]]
==== MS Power Control
Conforms to 3GPP TS 08.58 § 8.4.15 with these limitations:
._MS Power Control_ IE limitations
[options="header",cols="10%,30%,60%"]
|===
| TS 08.58 § | IE Name | Handling
| 9.3.31 | MS Power Parameters | _ignored_
|===
[[SACCH_INFO_MODIFY]]
==== SACCH Info Modify
Conforms to 3GPP TS 08.58 § 8.4.20, with these exceptions:
._SACCH Info Modify_ IE limitations
[options="header",cols="10%,30%,60%"]
|===
| TS 08.58 § | IE Name | Handling
| 9.3.30 | System Info Type | See below for available types
| 9.3.23 | Starting Time | not supported, provokes an _Error Report_ response
|===
._System Info Type_ values that can occur on the SACCH
[options="header",width="50%",cols="20%,80%"]
|===
| Value | Name
| 0x05 | RSL_SYSTEM_INFO_5
| 0x06 | RSL_SYSTEM_INFO_6
| 0x0d | RSL_SYSTEM_INFO_5bis
| 0x0e | RSL_SYSTEM_INFO_5ter
| 0x47 | RSL_EXT_MEAS_ORDER
| 0x48 | RSL_MEAS_INFO
|===
[[BCCH_INFORMATION]]
==== BCCH Information
Conforms to 3GPP TS 08.58 § 8.5.1, with these limitations and extensions:
._BCCH Information_ IE details
[options="header",cols="10%,30%,60%"]
|===
| TS 08.58 § | IE Name | Handling
| 9.3.30 | System Info Type | See <<SACCH_INFO_MODIFY>> for available types
| 9.3.11 | L3 Info | This IE may be included instead of a 9.3.39 _Full BCCH Info_ IE.
The _Full BCCH Info_ takes precedence over _L3 Info_.
To stop SI transmission, both of these IEs must be omitted.
|===
[[CHANNEL_REQUIRED]]
==== Channel Required
Conforms to 3GPP TS 08.58 § 8.5.3, with these limitations:
._Channel Required_ message IE details
[options="header",cols="10%,30%,60%"]
|===
| TS 08.58 § | IE Name | Handling
| 9.3.16 | Physical Context | never sent by OsmoBTS
|===
[[PAGING_COMMAND]]
==== Paging Command
Conforms to 3GPP TS 08.58 § 8.5.5, with these limitations:
._Paging Command_ message IE details
[options="header",cols="10%,30%,60%"]
|===
| TS 08.58 § | IE Name | Handling
| 9.3.49 | eMLPP Priority | _ignored_
|===
NOTE: If adding the identity to the paging queue fails, the BSC is not notified
in any way.
[[SMS_BROADCAST_COMMAND]]
=== SMS Broadcast Command
Conforms to 3GPP TS 08.58 § 8.5.8, with these limitations:
._Broadcast Command_ message IE details
[options="header",cols="10%,30%,60%"]
|===
| TS 08.58 § | IE Name | Handling
| 9.3.44 | SMSCB Channel Indicator | _ignored_
|===
[[RF_RESOURCE_INDICATION]]
==== RF Resource Indication
This message does not conform to 3GPP TS 08.58 § 8.6.1, in that it omits the
_Resource Information_ IE that would contain the actual payload data, which
renders this message void.
._RF Resource Indication_ message IE exceptions
[options="header",cols="10%,30%,60%"]
|===
| TS 08.58 § | IE Name | Handling
| 9.3.21 | Resource Information | OsmoBTS omits this IE, though TS 08.58
specifies it as mandatory.
|===
[[SACCH_FILLING]]
==== SACCH Filling
Conforms to 3GPP TS 08.58 § 8.6.2, with these limitations:
._SACCH Filling_ message IE limitations
[options="header",cols="10%,30%,60%"]
|===
| TS 08.58 § | IE Name | Handling
| 9.3.30 | System Info Type | See <<SACCH_INFO_MODIFY>> for available types
| 9.3.23 | Starting Time | _ignored_
|===
[[user_plane_txp_mgmt]]
=== User Plane Transport Management
This chapter defines the A-bis/IP specific RSL procedures that are
introduced in addition to the 3GPP TS 08.58 standard procedures.
In classic A-bis over E1, user plane traffic is carried over 16kBps
sub-slots of 64kBps E1 time-slots according to ETSI/3GPP TS 08.60. As
the E1 line is a dedicated line between BTS and BSC, no further
addressing information is required.
In A-bis/IP as described by the present document, new RSL procedures
have been introduced in order to deal with the different properties of
the underlying IP based transport medium.
[[rsl_crcx]]
==== RSL Create Connection (CRCX)
This procedure is used by the BSC to request the BTS to allocate + bind
to a BTS-local UDP port for the subsequent transmission of user-plane
data via RTP.
To do so, the BSC sends the *Create Connection (CRCX)* message. In case of
successful outcome, the BTS responds with *Create Connection (CRCX)
ACK*. In case of any error, the BTS responds with *Create Connection
(CRCX) NACK*.
See <<rsl_crcx_msg>>, <<rsl_crcx_msg_ack>>, <<rsl_crcx_msg_nack>>
[[rsl_mdcx]]
==== RSL Modify Connection (MDCX)
This procedure is used by the BSC to request the BTS to modify an
already-bound BTS-local UDP port for user-plane RTP. It is used in
particular to configure the remote IP address and UDP port to which the
BTS shall send user-plane RTP traffic. This remote address is normally
either a Media Gateway (MGW) of some sort, but could also be the RTP
socket of the corresponding other leg of a mobile-to-mobile call.
To modify a user-plane connection, the BSC sends the *Modify Connection*
message. In case of successful outcome, the BTS responds with
*Modify Connection (MDCX) ACK*. In case of any error, the BTS responds
with *Modify Connection (MDCX) NACK*.
See <<rsl_mdcx_msg>>, <<rsl_mdcx_msg_ack>>, <<rsl_mdcx_msg_nack>>
[[rsl_dlcx]]
==== RSL Delete Connection (DLCX)
This procedure is used by the BSC to request the BTS to delete an
already-existing BTS-local UDP port for user-plane RTP.
To delete a user-plane connection, the BSC sends the *Delete Connection
(DLCX)* message. In case of successful outcome, the BTS responds with
*Delete Connection (DLCX) ACK*. In case of any error, the BTS responds
with *Delete Connection (DLCX) NACK*.
See <<rsl_dlcx_msg>>, <<rsl_dlcx_msg_ack>>, <<rsl_dlcx_msg_nack>>
[[rsl_dlcx_ind]]
==== RSL Delete Connection (DLCX) Indication
When a BTS-local UDP connection for user-plane RTP is automatically
released at the time of RF CHANNEL RELEASE, the BTS sends a unilateral,
non-acknowledged *RSL Delete Connection (DLCX) Indication* to the BSC.
See <<rsl_dlcx_ind_msg>>
=== Message Formats and Contents
[[rsl_crcx_msg]]
==== Create Connection (CRCX)
This message is sent by the BSC to the BTS in order to request the
creation of a user-plane RTP connection for the specified *Channel
number*.
[options="header"]
[cols="30%,25%,15%,15%,15%"]
|===
| INFORMATION ELEMENT | REFERENCE | PRESENCE | FORMAT | LENGTH
| Message discriminator | 08.58 9.1 | M | V | 1
| Message type | <<own_msg_types>> | M | V | 1
| Channel number | 08.58 9.3.1 | M | TV | 2
| Destination IP Address | <<RSL_IE_IPAC_REMOTE_IP>> | O | TV | 5
| Destination IP Port | <<RSL_IE_IPAC_REMOTE_PORT>> | O | TV | 3
| IP Speech Mode | <<RSL_IE_IPAC_SPEECH_MODE>> | O | TV | 2
| RTP Payload Type 2 | <<RSL_IE_IPAC_RTP_PAYLOAD2>> | O | TV | 2
|===
[[rsl_crcx_msg_ack]]
==== Create Connection (CRCX) ACK
This message is sent by the BTS to the BSC in order to acknowledge the
successful outcome of creating a user-plane RTP connection. It is sent
in response to the *Create Connection (CRCX)*.
[options="header"]
[cols="30%,25%,15%,15%,15%"]
|===
| INFORMATION ELEMENT | REFERENCE | PRESENCE | FORMAT | LENGTH
| Message discriminator | 08.58 9.1 | M | V | 1
| Message type | <<own_msg_types>> | M | V | 1
| Channel number | 08.58 9.3.1 | M | TV | 2
| Connection Id | <<RSL_IE_IPAC_CONN_ID>> | M | TV | 3
| Source IP Address | <<RSL_IE_IPAC_LOCAL_IP>> | O | TV | 5
| Source IP Port | <<RSL_IE_IPAC_LOCAL_PORT>> | O | TV | 3
| RTP Payload Type 2 | <<RSL_IE_IPAC_RTP_PAYLOAD2>> | O | TV | 2
|===
[[rsl_crcx_msg_nack]]
==== Create Connection (CRCX) NACK
This message is sent by the BTS to the BSC in order to signal the
unsuccessful outcome of creating a user-plane RTP connection. It is
sent in response to the *Create Connection (CRCX)*.
[options="header"]
[cols="30%,25%,15%,15%,15%"]
|===
| INFORMATION ELEMENT | REFERENCE | PRESENCE | FORMAT | LENGTH
| Message discriminator | 08.58 9.1 | M | V | 1
| Message type | <<own_msg_types>> | M | V | 1
| Channel number | 08.58 9.3.1 | M | TV | 2
| Destination IP Address | <<RSL_IE_IPAC_REMOTE_IP>> | O | TV | 5
| Destination IP Port | <<RSL_IE_IPAC_REMOTE_PORT>> | O | TV | 3
| Cause | 08.58 9.3.26 | O | TLV | >= 3
|===
[[rsl_mdcx_msg]]
==== Modify Connection (MDCX)
This message is sent by the BSC to the BTS in order to modify the
properties of a user-plane RTP connection.
[options="header"]
[cols="30%,25%,15%,15%,15%"]
|===
| INFORMATION ELEMENT | REFERENCE | PRESENCE | FORMAT | LENGTH
| Message discriminator | 08.58 9.1 | M | V | 1
| Message type | <<own_msg_types>> | M | V | 1
| Channel number | 08.58 9.3.1 | M | TV | 2
| Connection Id | <<RSL_IE_IPAC_CONN_ID>> | O | TV | 3
| Destination IP Address | <<RSL_IE_IPAC_REMOTE_IP>> | O | TV | 5
| Destination IP Port | <<RSL_IE_IPAC_REMOTE_PORT>> | O | TV | 3
| IP Speech Mode | <<RSL_IE_IPAC_SPEECH_MODE>> | O | TV | 2
| RTP Payload Type 2 | <<RSL_IE_IPAC_RTP_PAYLOAD2>> | O | TV | 2
|===
[[rsl_mdcx_msg_ack]]
==== Modify Connection (MDCX) ACK
This message is sent by the BTS to the BSC in order to acknowledge the
successful modification of a user-plane RTP connection. It is sent in
response to a *Modify Connection (MDCX)*
[options="header"]
[cols="30%,25%,15%,15%,15%"]
|===
| INFORMATION ELEMENT | REFERENCE | PRESENCE | FORMAT | LENGTH
| Message discriminator | 08.58 9.1 | M | V | 1
| Message type | <<own_msg_types>> | M | V | 1
| Channel number | 08.58 9.3.1 | M | TV | 2
| Connection Id | <<RSL_IE_IPAC_CONN_ID>> | O | TV | 3
| Source IP Address | <<RSL_IE_IPAC_LOCAL_IP>> | C | TV | 5
| Source IP Port | <<RSL_IE_IPAC_LOCAL_PORT>> | C | TV | 3
| RTP Payload Type 2 | <<RSL_IE_IPAC_RTP_PAYLOAD2>> | O | TV | 2
|===
[[rsl_mdcx_msg_nack]]
==== Modify Connection (MDCX) NACK
This message is sent by the BTS to the BSC in order to signal the
unsuccessful outcome of modifying the user-plane RTP connection for the
specified Channel number. It is sent in response to the *Modify
Connection (MDCX)*.
[options="header"]
[cols="30%,25%,15%,15%,15%"]
|===
| INFORMATION ELEMENT | REFERENCE | PRESENCE | FORMAT | LENGTH
| Message discriminator | 08.58 9.1 | M | V | 1
| Message type | <<own_msg_types>> | M | V | 1
| Channel number | 08.58 9.3.1 | M | TV | 2
| Cause | 08.58 9.3.26 | M | TLV | >= 3
|===
[[rsl_dlcx_ind_msg]]
==== Delete Connection (DLCX) Indication
This message is sent by the BTS in order to indicate the automatic
deletion of a BTS-local UDP connection for user-plane RTP traffic at the
time of RF Channel release.
[options="header"]
[cols="30%,25%,15%,15%,15%"]
|===
| INFORMATION ELEMENT | REFERENCE | PRESENCE | FORMAT | LENGTH
| Message discriminator | 08.58 9.1 | M | V | 1
| Message type | <<own_msg_types>> | M | V | 1
| Channel number | 08.58 9.3.1 | M | TV | 2
| Connection Id | <<RSL_IE_IPAC_CONN_ID>> | M | TV | 3
| Connection Id | <<RSL_IE_IPAC_CONN_STAT>> | M | TV | 3
| Cause | 08.58 9.3.26 | M | TLV | >= 3
|===
[[rsl_dlcx_msg]]
==== Delete Connection (DLCX)
This message is sent by the BSC to the BTS in order to request the
disconnection of a user-plane RTP connection for the specified Channel
number.
[options="header"]
[cols="30%,25%,15%,15%,15%"]
|===
| INFORMATION ELEMENT | REFERENCE | PRESENCE | FORMAT | LENGTH
| Message discriminator | 08.58 9.1 | M | V | 1
| Message type | <<own_msg_types>> | M | V | 1
| Channel number | 08.58 9.3.1 | M | TV | 2
| Connection Id | <<RSL_IE_IPAC_CONN_ID>> | O | TV | 3
|===
[[rsl_dlcx_msg_ack]]
==== Delete Connection (DLCX) ACK
This message is sent by the BTS in order to signal the successful
outcome of deleting the user-plane RTP connection for the specified
Channel number. It is sent in response to the *Delete Connection
(DLCX)*.
[options="header"]
[cols="30%,25%,15%,15%,15%"]
|===
| INFORMATION ELEMENT | REFERENCE | PRESENCE | FORMAT | LENGTH
| Message discriminator | 08.58 9.1 | M | V | 1
| Message type | <<own_msg_types>> | M | V | 1
| Channel number | 08.58 9.3.1 | M | TV | 2
| Connection Id | <<RSL_IE_IPAC_CONN_ID>> | O | TV | 3
| Connection Statistics | <<RSL_IE_IPAC_CONN_STAT>> | C | TV | 29
|===
[[rsl_dlcx_msg_nack]]
==== Delete Connection (DLCX) NACK
This message is sent by the BTS in order to signal the unsuccessful
outcome of deleting the user-plane RTP connection for the specified
Channel number. It is sent in response to the *Delete Connection
(DLCX)*.
[options="header"]
[cols="30%,25%,15%,15%,15%"]
|===
| INFORMATION ELEMENT | REFERENCE | PRESENCE | FORMAT | LENGTH
| Message discriminator | 08.58 9.1 | M | V | 1
| Message type | <<own_msg_types>> | M | V | 1
| Channel number | 08.58 9.3.1 | M | TV | 2
| Connection Id | <<RSL_IE_IPAC_CONN_ID>> | O | TV | 3
| Cause | 08.58 9.3.26 | M | TLV | >= 3
|===
=== Information Element Codings
[[own_msg_types]]
==== A-bis/IP specific RSL Message discriminators
The following message descriminators are used in addition to those
indicated in 3GPP TS 08.58 Section 9.1:
.OsmoBTS specific new message discriminators
[options="header",cols="10%,50%,40%"]
|===
| Message Type | Message | This document §
| 0x70 | Create Connection (CRCX) | <<rsl_crcx_msg>>
| 0x71 | Create Connection (CRCX) ACK | <<rsl_crcx_msg_ack>>
| 0x72 | Create Connection (CRCX) NACK | <<rsl_crcx_msg_nack>>
| 0x73 | Modify Connection (MDCX) | <<rsl_mdcx_msg>>
| 0x74 | Modify Connection (MDCX) ACK | <<rsl_mdcx_msg_ack>>
| 0x75 | Modify Connection (MDCX) NACK | <<rsl_mdcx_msg_nack>>
| 0x76 | Delete Connection (DLCX) Indication | <<rsl_dlcx_ind_msg>>
| 0x77 | Delete Connection (DLCX) | <<rsl_dlcx_msg>>
| 0x78 | Delete Connection (DLCX) ACK | <<rsl_dlcx_msg_ack>>
| 0x79 | Delete Connection (DLCX) NACK | <<rsl_dlcx_msg_nack>>
|===
==== A-bis/IP specific RSL IEIs
The following Information Element Identifiers (IEIs) are used in
addition to those indicated in 3GPP TS 08.58 Section 9.3.1:
.A-bis/IP specific information elements
[options="header",cols="10%,50%,40%"]
|===
| IEI | Name | This document §
| 0xf0 | RSL_IE_IPAC_REMOTE_IP | <<RSL_IE_IPAC_REMOTE_IP>>
| 0xf1 | RSL_IE_IPAC_REMOTE_PORT | <<RSL_IE_IPAC_REMOTE_PORT>>
| 0xf3 | RSL_IE_IPAC_LOCAL_PORT | <<RSL_IE_IPAC_LOCAL_PORT>>
| 0xf4 | RSL_IE_IPAC_SPEECH_MODE | <<RSL_IE_IPAC_SPEECH_MODE>>
| 0xf5 | RSL_IE_IPAC_LOCAL_IP | <<RSL_IE_IPAC_LOCAL_IP>>
| 0xf6 | RSL_IE_IPAC_CONN_STAT | <<RSL_IE_IPAC_CONN_STAT>>
| 0xf8 | RSL_IE_IPAC_CONN_ID | <<RSL_IE_IPAC_CONN_ID>>
| 0xfc | RSL_IE_IPAC_RTP_PAYLOAD2 | <<RSL_IE_IPAC_RTP_PAYLOAD2>>
|===
[[RSL_IE_IPAC_REMOTE_IP]]
==== RSL_IE_IPAC_REMOTE_IP
This information element contains the remote (MGW side) IPv4 address in
network byte order. It is encoded as fixed-size element with one byte
IEI followed by four bytes IPv4 address.
[[RSL_IE_IPAC_REMOTE_PORT]]
==== RSL_IE_IPAC_REMOTE_PORT
This information element contains the remote (MGW side) UDP port in
network byte order. It is encoded as fixed-size element with one byte
IEI followed by two bytes UDP port number.
[[RSL_IE_IPAC_LOCAL_PORT]]
==== RSL_IE_IPAC_LOCAL_PORT
This information element contains the local (BTS side) IPv4 address in
network byte order. It is encoded as fixed-size element with one byte
IEI followed by two bytes UDP port number.
[[RSL_IE_IPAC_SPEECH_MODE]]
==== RSL_IE_IPAC_SPEECH_MODE
This information element encodes the speech mode. It is set according
to the voice codec used on the connection. It is encoded as a fixed-size
element of two bytes, with one byte IEI followed by one byte Speech mode
indicator.
.A-bis/IP Speech Mode Indicator Values
[options="header",width="40%",cols="20%,80%"]
|===
| Value | Description
| 0x00 | TCH/F with FR codec
| 0x01 | TCH/F with EFR codec
| 0x02 | TCH/F with AMR codec
| 0x03 | TCH/H with HR codec
| 0x05 | TCH/H with AMR codec
|===
[[RSL_IE_IPAC_LOCAL_IP]]
==== RSL_IE_IPAC_LOCAL_IP
This information element contains the local (BTS side) IPv4 address in
network byte order. It is encoded as fixed-size element with one byte
IEI followed by four bytes IPv4 address.
[[RSL_IE_IPAC_CONN_STAT]]
==== RSL_IE_IPAC_CONN_STAT
This information element contains statistics about the RTP connection.
It is encoded as 29 bytes, with the first byte as IEI and 28 bytes
fixed-length payload encoded as follows:
.A-bis/IP Connection Statistics
[options="header",width="60%",cols="15%,15%,70%"]
|===
| Offset | Size | Description
| 0 | 4 | Total number of RTP packets sent
| 4 | 4 | Total number of octets sent
| 8 | 4 | Total number of RTP packets received
| 12 | 4 | Total number of octets received
| 16 | 4 | Total number of lost packets in Rx direction
| 20 | 4 | Inter-arrival Jitter
| 24 | 4 | Average transmission delay
|===
All the above values are each encoded in network byte order.
A detailed definition of the individual values is given in RFC 1889.
[[RSL_IE_IPAC_CONN_ID]]
==== RSL_IE_IPAC_CONN_ID
This IE is a TV with a value length of two bytes. The value is a 16 bit
connection ID in network byte order.
[[RSL_IE_IPAC_RTP_PAYLOAD2]]
==== RSL_IE_IPAC_RTP_PAYLOAD2
This information element contains the RTP payload identifier, which is
used in the PT (Payload Type) field of the RTP header in subsequent
transmissions of the RTP flow.
=== A-bis RSL Initialization / BTS bring-up
Upon receiving the 'IPA RSL CONNECT' OML message by the respective
'Baseband Transceiver' MO, the BTS proceeds with establishing a separate
TCP connection for the given TRX.
[[rsl-msc-pri]]
.A-bis RSL BTS bring-up for primary TRX
["mscgen"]
----
include::rsl-startup-pri.msc[]
----
[[rsl-msc-sec]]
.A-bis RSL BTS bring-up for secondary TRXs
["mscgen"]
----
include::rsl-startup-sec.msc[]
----
As can be seen by the differences between <<rsl-msc-pri>> and
<<rsl-msc-sec>>, the initialization of the primary and secondary TRX
slightly differ. As the secondary TRX has no BCCH, it does not (need
to) receive any 'RSL BCCH INFORMATION' messages from the BSC.

33
doc/manuals/abis/rtp.adoc Normal file
View File

@ -0,0 +1,33 @@
== User-Plane Traffic via RTP
RTP (Realtime Transfer Protocol) is a protocol for streaming of audio
and video streaming data. It is specified by IETF RFC 1889.
OsmoBTS A-bis/IP implements RTP as transport medium for circuit-switched
user-plane traffic, contrary to the E1 sub-slot based transport as
specified in 3GPP TS 08.60.
The RTP transport endpoint parameters are configured using the RSL User
Plane Transport Management procedures described in <<user_plane_txp_mgmt>>.
RTCP is implemented in addition to RTP, on a UDP port number of the RTP
port incremented by one.
=== RTP Payload Formats
The RTP payload format depends on the voice codec used on the radio
channel. The OsmoBTS is simply passing the GSM speech frames between
the Um radio interface channels and the RTP payload (and vice-versa).
No transcoding function is implemented in the BTS!
.RTP Payload formats
[options="header",width="60%",cols="15%,15%,70%"]
|===
| TCH | Codec | RTP payload format specification
| TCH/F | FR | IETF RFC 3551 Section 4.5.8
| TCH/F | EFR | IETF RFC 3551 Section 4.5.9
| TCH/F | AMR | IETF RFC 4867
| TCH/H | HR | IETF RFC 5993
| TCH/H | AMR | IETF RFC 4867
|===

120
doc/manuals/chapters/architecture.adoc Normal file
View File

@ -0,0 +1,120 @@
== OsmoBTS software architecture
=== OsmoBTS PHY interface abstraction
The OsmoBTS PHY interface serves as an internal abstraction layer
between given PHY hardware (as provided by the bts_model) and the actual
logical transceivers (TRXs) of a BTS inside the OsmoBTS code base.
==== PHY link
A PHY link is a physical connection / link towards a given PHY. This
might be, for example,
* a set of file descriptors to device nodes in the /dev/ directory
(sysmobts, litecell15)
* a packet socket for sending raw Ethernet frames to an OCTPHY
* a set of UDP sockets for interacting with OsmoTRX
Each PHY interface has a set of attribute/parameters and a list of 1 to
n PHY instances.
PHY links are numbered 0..n globally inside OsmoBTS.
Each PHY link is configured via the VTY using its individual top-level
vty node. Given the different bts-model / phy specific properties, the
VTY configuration options (if any) of the PHY instance differ between
BTS models.
The PHY links and instances must be configured above the BTS/TRX nodes
in the configuration file. If the file is saved via the VTY, the code
automatically ensures this.
==== PHY instance
A PHY instance is an instance of a PHY, accessed via a PHY link.
In the case of osmo-bts-sysmo and osmo-bts-trx, there is only one
instance in every PHY link. This is due to the fact that the API inside
that PHY link does not permit for distinguishing multiple different
logical TRXs.
Other PHY implementations like the OCTPHY however do support addressing
multiple PHY instances via a single PHY link.
PHY instances are numbered 0..n inside each PHY link.
Each PHY instance is configured via the VTY as a separate node beneath each
PHY link. Given the different bts-model / phy specific properties, the
VTY configuration options (if any) of the PHY instance differ between
BTS models.
==== Mapping PHY instances to TRXs
Each TRX node in the VTY must use the 'phy N instance M' command in
order to specify which PHY instance is allocated to this specific TRX.
=== Internal control flow
==== start-up / sequencing during OsmoBTS start
.Control flow at OsmoBTS start-up procedure
[options="header",cols="10%,35%,55%"]
|===
| section | function | description
| bts-specific | main() | Entering main() from glibc
| common | bts_main() | initialization of talloc contexts
| common | bts_log_init() | initialization of logging
| common | handle_options() | common option parsing
| bts-specific | bts_model_handle_options() | model-specific option parsing
| common | gsm_bts_alloc() | allocation of BTS/TRX/TS data structures
| common | vty_init() | Initialziation of VTY core, libosmo-abis and osmo-bts VTY
| common | main() | Setting of scheduler RR priority (if configured)
| common | main() | Initialization of GSMTAP (if configured)
| common | bts_init() | configuration of defaults in bts/trx/s object
| bts-specific | bts_model_init | ?
| common | abis_init() | Initialization of libosmo-abis
| common | vty_read_config_file() | Reading of configuration file
| bts-specific | bts_model_phy_link_set_defaults() | Called for every PHY link created
| bts-specific | bts_model_phy_instance_set_defaults() | Called for every PHY Instance created
| common | bts_controlif_setup() | Initialization of Control Interface
| bts-specific | bts_model_ctrl_cmds_install() | Install model-specific control interface commands
| common | telnet_init() | Initialization of telnet interface
| common | pcu_sock_init() | Initializaiton of PCU socket
| common | main() | Installation of signal handlers
| common | abis_open() | Start of the A-bis connection to BSC
| common | phy_links_open() | Iterate over list of configured PHY links
| bts-specific | bts_model_phy_link_open() | Open each of the configured PHY links
| common | write_pid_file() | Generate the pid file
| common | osmo_daemonize() | Fork as daemon in background (if configured)
| common | bts_main() | Run main loop until global variable quit >= 2
|===
==== At time of OML establishment
.Control flow at time of OML establishment
[options="header",cols="10%,35%,55%"]
|===
| section | function | description
| bts-specific | bts_model_oml_estab() | Called by core once OML link is established
| bts-specific | bts_model_check_oml() | called each time OML sets some attributes on a MO, checks if attributes are valid
| bts-specific | bts_model_apply_oml() | called each time OML sets some attributes on a MO, stores attribute contents in data structures
| bts-specific | bts_model_opstart() | for NM_OC_BTS, NM_OC_SITE_MANAGER, NM_OC_GPRS_NSE, NM_OC_GPRS_CELL, NMO_OC_GPRS_NSVC
| bts-specific | bts_model_opstart() | for NM_OC_RADIO_CARRIER for each trx
| bts-specific | bts_model_opstart() | for NM_OC_BASEB_TRANSC for each trx
| bts-specific | bts_model_opstart() | for NM_OC_CHANNEL for each timeslot on each trx
| bts-specific | bts_model_change_power() | change transmit power for each trx (power ramp-up/ramp-down)
|===
==== At time of RSL connection loss
.Control flow at time of RSL connection loss
[options="header",cols="10%,35%,55%"]
|===
| section | function | description
| bts-specific | bts_model_abis_close() | called when either one of the RSL links or the OML link are down
|===

405
doc/manuals/chapters/bts-models.adoc Normal file
View File

@ -0,0 +1,405 @@
== OsmoBTS hardware support
OsmoBTS consists of a generic part common to all BTS, and a
hardware-specific _common_ part, and a _hardware-specific_ part. The
hardware specific part is generally referred to as the _bts_model_ code.
The common part includes the core BTS architecture as well as code for
implementing the external interfaces such Abis, control, PCU socket and
GSMTAP.
The bts_model parts include support for driving one particular
implementation of a GSM physical layer (PHY). Such a physical layer
implementation can come in many forms. Sometimes it runs on a general
purpose CPU, sometimes on a dedicated ARM core, a dedicated DSP, a
combination of DSP and FPGA.
Every PHY implementation offers some kind of primitives by which the PHY
can be controlled, and by which the PHY exchanges data with the higher
layers of the protocol stack in the OsmoBTS code.
The PHY-specific primitives are encapsulated in the bts_model code, and
offered as a PHY-independent _L1SAP_ interface towards the common part of
OsmoBTS.
In addition, each bts_model implements a set of functions that the
common part calls. Those functions are pre-fixed by bts_model_.
Each bts_model may offer
* model-specific VTY commands for both configuration and run-time interaction
* model-specific command line arguments
* model-specific control interface commands
== `osmo-bts-sysmo` for sysmocom sysmoBTS
The sysmocom sysmoBTS is a range of GSM BTSs basd around an embedded
system implementing the PHY in a combination of DSP+FPGA. The PHY is
configured by a set of primitives described by header files. Those
primitives are exchanged ove a set of message queues exposed on the
Linux-running ARM core via device nodes in `/dev/msgq/`. Internally,
the message queues map to shared memory between the Linux-running ARM
core and the DSP running the PHY implementation.
The OsmoBTS bts_model code for the sysmoBTS can be found in the
`src/osmo-bts-sysmo` sub-directory of the OsmoBTS code base.
`osmo-bts-sysmo` has been the primary target platform for
OsmoBTS for many years and is thus the most feature-complete and mature
platform supported by OsmoBTS at this point.
The sysmoBTS PHY supports a direct PHY interface to OsmoPCU, reducing
the latency and amount of primitives that OsmoBTS would otherwise need
to pass through from the PHY message queues to the PCU socket and
vice-versa.
=== `osmo-bts-sysmo` specific command line arguments
*--dsp-trace 'DSPMASK'*::
Set the DSP trace flags (a single hexadecimal 32bit value).
This has been deprecated by VTY based commands, see
<<osmo-bts-sysmo-dsp-trace>> for further information.
*--pcu-direct*::
Indicate that an external PCU (e.g. OsmoPCU) will directly
open the DSP messge queues to the PHY / PH-SAP, and only MPH
primitives are passed via OsmoBTS.
=== `osmo-bts-sysmo` specific VTY commands
For a auto-generated complete syntax reference of the VTY commands,
please see the associated _OsmoBTS VTY reference manual_
<<vty-ref-osmobts>>. The section
below only lists the most important commands.
==== at the 'SHOW' node
===== `show trx 0 clock-source`
Display the currently active clock source configuration for the TRX
[[osmo-bts-sysmo-dsp-trace]]
===== `show trx 0 dsp-trace-flags`
Show the currently active DSP trace flags for the TRX
===== `trx 0 dsp-trace-flag`
Use this command to enable/disable/configure the DSP tracing flags that
define what debug messages will appear on `/dev/rtfifo/dsp_trace`.
==== at the 'ENABLE' node
===== `trx 0 tx-power <-110-100>`
Change the current TRX transmit power to the given value in dBm.
===== `trx 0 rf-clock-info reset`
Part of the clock calibration procedure:
Reset the clock correction value.
===== `trx 0 rf-clock-info correct`
Part of the clock calibration procedure:
Apply the current measured correction value between the reference clock
and the local clock.
==== at the 'PHY instance' node
==== `clock-calibration eeprom`
Obtain clock calibration value from EEPROM.
==== `clock-calibration default`
Use hardware default clock calibration value.
==== `clock-calibration <-4095-4095>`
Use specified clock calibration value (not EEPROM/default).
==== `clock-source (tcxo|ocxo|ext|gps)`
Specify the clock source for the PHY:
tcxo::
Use the TCXO. This is the default on sysmoBTS 2050.
ocxo::
Use the OCXO (only valid on units equipped with OCXO). This is
the default on all sysmoBTS 1002/1020/1100 and SOB-BTS.
ext::
Use the external clock input.
gps::
Use the clock derived from GPS. You shouldn't use this clock
directly, but rather use the TCXO and regularly re-calibrate
against GPS.
==== `trx-calibration-path PATH`
Use calibration files from the given 'PATH', rather tan calibration
values from the EEPROM.
=== `osmo-bts-sysmo` specific control interface commands
==== trx.0.clock-info
Obtain information on the current clock status:
----
bsc_control.py -d localhost -p 4238 -g trx.0.clock-info
Got message: GET_REPLY 1 trx.0.clock-info -100,ocxo,0,0,gps
----
which is to be interpreted as:
* current clock correction value is -100 ppb
* current clock source is OCXO
* deviation between clock source and calibration source is 0 ppb
* resolution of clock error measurement is 0 ppt (0 means no result yet)
* current calibration source is GPS
When this attribute is set, any value passed on is discarded, but the clock
calibration process is re-started.
==== trx.0.clock-correction
This attribute can get and set the current clock correction value:
----
bsc_control.py -d localhost -p 4238 -g trx.0.clock-correction
Got message: GET_REPLY 1 trx.0.clock-correction -100
----
----
bsc_control.py -d localhost -p 4238 -s trx.0.clock-correction -- -99
Got message: SET_REPLY 1 trx.0.clock-correction success
----
== `osmo-bts-trx` for OsmoTRX
OsmoTRX is a C-language implementation of the GSM radio modem,
originally developed as the 'Transceiver' part of OpenBTS. This radio
modem offers an interface based on top of UDP streams.
The OsmoBTS bts_model code for OsmoTRX is called
`osmo-bts-trx`. It implements the UDP stream interface of
OsmoTRX, so both parts can be used together to implement a complete GSM
BTS based on general-purpose computing SDR.
As OsmoTRX is general-purpose software running on top of Linux, it is
thus not tied to any specific physical hardware. At the time of this
writing, OsmoTRX supports a variety of Ettus USRP SDRs via the UHD
driver, as well as the Fairwaves UmTRX and derived products.
OsmoTRX is not a complete GSM PHY but 'just' the radio modem. This
means that all of the Layer 1 functionality such as scheduling,
convolutional coding, etc. is actually also implemented inside OsmoBTS.
As such, the boundary between OsmoTRX and `osmo-bts-trx` is at
a much lower interface, which is an internal interface of other more
traditional GSM PHY implementations.
Besides OsmoTRX, there are also other implementations (both Free
Software and proprietary) that implement the same UDP stream based radio
modem interface.
=== `osmo-bts-trx` specific VTY commands
For a auto-generated complete syntax reference of the VTY commands,
pleas see the associated _OsmoBTS VTY reference manual_
<<vty-ref-osmobts>>. The section below only lists the most important
commands.
==== at the 'SHOW' node
===== `show transceivers`
Display information about configured/connected OsmoTRX transceivers in
human-readable format to current VTY session.
==== at the 'PHY' configuration node
===== `osmotrx ip HOST`
Set the IP addess of the OsmoTRX transceiver to which we should connect
to.
===== `osmotrx base-port (local|remote) <0-65535>`
Configure the base UDP port for the OsmoTRX interface for either the
local (OsmoBTS) or remote (OsmoTRX) side of the UDP flows.
===== `osmotrx fn-advance <0-30>`
Set the number of frames to be transmitted to transceiver in advance of
current GSM frame number.
===== `osmotrx rts-advance <0-30>`
Set the number of frames to be requested from PCU in advance of current
frame number. Do not change this unless you have a good reason!
===== `osmotrx rx-gain <0-50>`
Set the receiver gain (configured in the hardware) in dB.
===== `osmotrx tx-attenuation <0-50>`
Set the transmitter attenuation (configured in the hardware) in dB.
===== `osmotrx tx-attenuation oml`
Use the Value in the A-bis OML Attribute `MAX_POWER_REDUCTION` as
transmitter attenuation.
==== at the 'PHY Instance' configuration node
===== `slotmask (1|0) (1|0) (1|0) (1|0) (1|0) (1|0) (1|0) (1|0)`
Configure which timeslots should be active on this TRX. Normally all
timeslots are enabled, unless you are running on a cpu-constrained
deeply embedded system.
===== `osmotrx maxdly <0-31>`
Set the maximum delay for received symbols (in number of GSM symbols).
== `osmo-bts-octphy` for Octasic OCTPHY-2G
The Octasic OCTPHY-2G is a GSM PHY implementation inside an Octasic
proprietary 24-core DSP called OCTDSP.
This DSP has a built-in Gigabit Ethernet interface, over which it
exchanges PHY-layer primitives in raw Ethernet frames with the upper
layers running on another CPU attached to the same Ethernet. Those
primitives are described in a set of C-language header files.
OsmoBTS implements the raw Ethernet frame based primitives as well as
the associated transport protocol (OKTPKT/OCTVC1) in the
`osmo-btso-octphy` bts_model code.
You can run the `osmo-bts-octphy` on any system connected to the same
Ethernet as the OCTDSP running the OCTPHY. This can be either an
embedded ARM or x86 SoM part of the OCTBTS hardware, or it can be any
other Linux system attached via an Ethernet switch.
Each OCTDSP running OCTSDR-2G offers a set of primitives part of a
OCTPKT session, which is mapped to an OsmoBTS PHY link. Depending on
the OCTSDR-2G software version, you may create multiple software TRX by
creating multiple OsmoBTS PHY instances inside that PHY link.
Multiple DSPs may exsist in one circuit board, then each of the DSPs is
interfaced by one OsmoBTS PHY link, and each of them may have one or
more OsmoBTS PHY instances creating a Multi-TRX configuration.
== `osmo-bts-litecell15` for Nutaq/Nuran LiteCell 1.5
The Nutaq/Nuran LiteCell 1.5 implements a dual-transceiver GSM BTS based
on a mixed ARM/DSP/FPGA architecture. The PHY layer is implemented on
DSP/FPGA and similar to that of the sysmoBTS: It exchanges primitives
described in a set of C-language header files over message queues
between the ARM and the DSP.
This interface is implemented in the `osmo-bts-litecell15` bts_model of
OsmoBTS. You would run `osmo-bts-litecell15` on the ARM/Linux processor
of the Litecell 1.5.
The two transceivers of the Litecell 1.5 each have their own set of DSP
message queues. Each set of message queues is wrapped into one OsmoBTS
PHY link, offering one OsmoBTS PHY instance.
The Litecell 1.5 PHY supports a direct PHY interface to OsmoPCU,
reducing the latency and amount of primitives that OsmoBTS would
otherwise need to pass through from the PHY message queues to the PCU
socket and vice-versa.
=== `osmo-bts-trx` specific VTY commands
For a auto-generated complete syntax reference of the VTY commands,
please see the associated _OsmoBTS VTY reference manual_
<<vty-ref-osmobts>>. The section below only lists the most important
commands.
==== at the 'SHOW' node
===== `show phy <0-255> system-information`
Show information about the hardware platform, DSP and OCTPHY-2G software
version.
===== `show phy <0-255> rf-port-stats <0-1>`
Show information about the RF port interfaces.
===== `show phy <0-255> clk-sync-stats`
Show information about the clock synchronization manager.
==== at the 'PHY' configuration node
===== `octphy hw-addr HWADDR`
Specify the Ethernet hardware address (mac address) of the DSP running
the OCTPHY-2G software for this PHY link.
===== `octphy net-device NAME`
Specify the Ethernet network device (like `eth0`) through which the DSP
can be reached from OsmoBTS.
===== `octphy rf-port-index <0-255>`
Specify which RF port should be used for this PHY link.
===== `octphy rx-gain <0-73>`
Configure the receiver gain in dB.
===== `octphy tx-attenuation <0-359>`
Configure the transmitter attenuation in quarter-dB
== `osmo-bts-virtual` for Virtual Um Interface
This is a special BTS model used for research, simulation and testing.
Rather than communicating over a wireless RF interface, the GSM Um
messages are encapsulated over GSMTAP/UDP/IP.
At the time of writing, this functionality is not fully completed. It
is the idea to adopt the OsmocomBB MS-side GSM implementation to
interface with this virtual Um interface, so that many instances of
virtual MS can connect to some instances of OsmoBTS, testing MS, BTS,
BSC and core network functionality.
=== `osmo-bts-trx` specific VTY commands
For a auto-generated complete syntax reference of the VTY commands,
please see the associated _OsmoBTS VTY reference manual_
<<vty-ref-osmobts>>. The section below only lists the most important
commands.
==== at the 'PHY' config node
===== `virtual-um net-device NETDEV`
Configure the network device used for sending/receiving the virtual Um
interface messages (e.g. `eth0`).
===== `virtual-um udp-port <0-65535>`
Configure the UDP port used for sending/receiving the virtual Um
interface messages (default: GSMTAP 2775).
===== `virtual-um multicast-group GROUP`
Configure the IP multicast group used for sending/receiving the virtual
Um interface messages.

154
doc/manuals/chapters/configuration.adoc Normal file
View File

@ -0,0 +1,154 @@
== BTS Configuration
The role of the BTS is to handle the GSM radio interface. When the BTS
application is starting, the A-bis OML connection is established towards
the BSC. Almost all BTS configuration (such as ARFCN, channel
configuration, transmit power, etc.) will be sent from the BSC to the
BTS via OML messages. After OML start-up has competed, the BSC will
instruct the BTS to establish the RSL connections.
Given that most configuration is downloaded from the BSC into the BTS at
start-up time, only some very basic settings have to be made in the
OsmoBTS software.
=== Command Line Options
Ths OsmoBTS executables (`osmo-bts-sysmo`, `osmo-bts-trx`,
`osmo-bts-octphy`, `osmo-bts-litecell15`, ...) share the following
generic command line options:
==== SYNOPSIS
*osmo-bts-sysmo* [-h|-V] [-d 'DBGMASK'] [-D] [-c 'CONFIGFILE' ] [-s] [-T] [-e 'LOGLEVEL'] [-r 'PRIO'] [-i 'GSMTAP-IP'] [-t <1-255>]
==== 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-bts.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 further information.
*-T, --timestamp*::
Enable time-stamping of log messages to stderr. This has mostly
been deprecated by VTY based logging configuration, see
<<logging>> for further 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 further information.
*-r, --realtime 'PRIO'*::
Enable use of the Linux kernel realtime priority scheduler with
the specified priority.
It is recommended you use this option on low-performance
embedded systems or systems that encounter high non-GSM/GPRS
load.
*-i, --gsmtap-ip 'GSMTAP-IP'*::
Specify the destination IP address for GSMTAP messages.
*-t, --trx-num <1-255>*::
Specify the number of TRX supported by this BTS.
There may be additional, hardware specific command line options by the
different bts_model implementations.
=== Configuration using the VTY
Most configuration as well as run-time monitoring and system
introspection is implemented using a command-line based interface
called _VTY_. A full reference syntax of all existing VTY command is
available as a separate document.
See <<vty>> for further information on the VTY.
==== Required BTS/TRX configuration
There are some settings that have to be configured locally in the
sysmoBTS, as they cannot be set remotely from the BSC. Those
settings are stored in the OsmoBTS configuration file, which commonly
is stored in `/etc/osmocom/osmo-bts.cfg`.
.Example Minimal configuration file
----
!
! OsmoBTS (0.0.1.100-0455) configuration saved from vty
!!
!
phy 0 <1>
instance 0 <2>
bts 0 <3>
band DCS1800
ipa unit-id 1801 0 <4>
oml remote-ip 192.168.100.11 <5>
trx 0 <6>
phy 0 instance 0 <7>
----
<1> You must configure at least one PHY link by means of the PHY node
<2> You must configure at least one PHY instance in the PHY link
<3> There is always exactly one BTS (`bts 0`) configured in OsmoBTS
<4> The `ipa unit-id` is what is used to identify this BTS to the BSC
<6> The OML Remote IP is the IP address of the BSC, to which the BTS shall connect to.
<6> There must be at least one trx (`trx 0`) in each BTS
<7> Every TRX must be mapped to a specific PHY instance this way
For a full reference of all available VTY configuration parameters,
please refer to the OsmoBTS VTY Reference document.
[[gsmtap]]
==== Configuring GSMTAP tracing
In addition to being able to obtain pcap protocol traces of the A-bis
communication and the text-based logging from the OsmoBTS
software, there is also the capability of tracing all communication on
the radio interface. To do so, OsmoBTS can encapsulate
MAC blocks (23byte messages at the L2-L1 interface) into _GSMTAP_ and send
them via UDP/IP. At that point, they can be captured with utilities like
*tcpdump* or *tshark* for further analysis by the *wireshark* protocol
analyzer.
In order to activate this feature, you first need to make sure to start
OsmoBTS using the `-i` or `--gsmtap-ip` command line option, specifying
the destination IP address for the GSMTAP messages. In most cases,
using 127.0.0.1 for passing the messages over the loopback (`lo`) device
will be sufficient.
OsmoBTS can selectively trace such messages by their L1 SAPI, for both
Rx and Tx. For a complete list of L1 SAPI values, please refer to the
_OsmoBTS VTY reference manual_ <<vty-ref-osmobts>>.
For example, to enable GSMTAP tracing for messages on all SDCCH
channels, you can use the gsmtap-sapi sdcch command at the CONFIG TRX
node of the OsmoBTS VTY.
.Example: Enabling GSMTAP for SDCCH
----
OsmoBTS> enable
OsmoBTS# configure terminal
OsmoBTS(config)# bts
OsmoBTS(bts)# trx 0
OsmoBTS(trx)# gsmtap-sapi sdcch
OsmoBTS(trx)# write <1>
----
<1> the `write` command will make the configuration persistent in the
configuration file. This is not required if you wish to enable GSMTAP
only in the current session of OsmoBTS.
De-activation can be performed similarly by using the `no gsmtap-sapi
sdcch` command at the `trx` node of the OsmoBTS VTY.
From the moment they are enabled via VTY, GSMTAP messages will be
generated and sent in UDP encapsulation to the IANA-registered UDP port
for GSMTAP (4729) at the IP address specified in the command line
argument.

130
doc/manuals/chapters/interfaces.adoc Normal file
View File

@ -0,0 +1,130 @@
== OsmoBTS Interfaces
OsmoBTS offers a set of interfaces to interact with external entities:
* A-bis/IP interface to talk to the BSC
* bts_model specific PHY interface
* VTY interface
* Osmocom control interface
* GSMTAP interface
* PCU interface
=== OsmoBTS Abis/IP Interface
OsmoBTS implements the GSM A-bis interface as described in the relevant
3GPP specifications:
* A-bis RSL according to 3GPP TS 08.58
* A-bis OML according to 3GPP TS 12.21
As the 3GPP specified A-bis only over E1 interfaces and not over IP,
significant enhancements and modifications have been performed as opposed
to the 3GPP specifications. Nevertheless, the implementation tries to
stay as close a possible to the 3GPP specifications.
Please see the _OsmoBTS Abis Protocol Specification_
<<osmobts-abis-spec>> for more information on this subject.
=== bts_model specific PHY interface
This interface is specific to the bts_model that OsmoBTS was compiled
for. It can take any form as required by the respective hardware.
Please see the PHY documentation of your respective BTS hardware for more
details.
=== OsmoBTS VTY Interface
See <<vty>> for further information.
=== OsmoBTS Control Interface
The general structure of the Omsocom control interface is described in
<<common-control-if>>.
The number of control interface commands/attributes is currently quite
limited and largely depends on the bts_model used.
==== trx.N.thermal-attenuation
The idea of this paramter is to attenuate the system output power as part of
thermal management. In some cases the PA might be passing a critical level,
so an external control process can use this attribute to reduce the system
output power.
Please note that all values in the context of transmit power calculation
are integers in milli-dB (1/10000 bel), so the below example is setting
the attenuation at 3 dB:
----
bsc_control.py -d localhost -p 4238 -s trx.0.thermal-attenuation 3000
Got message: SET_REPLY 1 trx.0.thermal-attenuation 3000
----
----
bsc_control.py -d localhost -p 4238 -g trx.0.thermal-attenuation
Got message: GET_REPLY 1 trx.0.thermal-attenuation 3000
----
=== OsmoBTS GSMTAP Interface
GSMTAP is a standard created by Osmocom to UDP-encapsulate GSM protocol
messages normally communicated over non-IP interfaces for the primary
purpose of protocol analysis in the wireshark dissector.
The initial purpose was to encapsulate GSM Um frames including some
meta-data like ARFCN and GSM frame number into something that can be
parsed and dispatched within the wireshark dissector.
This interface has since been extended to many other
GSM/GPRS/UMTS interfaces and protocols, and even to TETRA and GMR.
In OsmoBTS, it is possible to export both uplink and downlink Um
messages via GSMTAP. There is a set of VTY configuration options to
specify for which logical channels of the Um interface GSMTAP messages
shall be emitted, and to which destination IP address they shall be
sent.
Using GSMTAP it is possible to place a virtual tap at the air interface
between BTS and MS, without going through the trouble of setting up an
actual radio receiver at the same frequencies. Also, GSMTAP export is
performed before the Um air-interface encryption (A5) is performed, so
all frames are always in plain text.
Please refer to <<gsmtap>> for more information on how to configure and
use this interface.
=== OsmoBTS PCU Socket Interface
In order to assist the provisioning of GPRS services over the same radio
interface as circuit-switched GSM, OsmoBTS exposes a Unix domain socket
based interface towards OsmoPCU.
OsmoPCU is the Osmocom implementation of the GPRS Packet Control Unit
(PCU), which is co-located with the BTS in the Osmocom implementation.
Contrary to that, many classic E1-based implementations of the GSM RAN
co-locate the PCU with the BSC. However, the GSM specifications keep
the location up to the implementor.
The PCU socket interface serves the following purposes:
* to pass PCU relevant configuration from BTS to PCU
* to forward paging requests from BTS to PCU
* to forward RACH Requests from BTS to PCU
Depending on your bts_model, the PCU may also be passing actual
PH-DATA.request / PH-DATA.indication / PH-RTS.indication primitives for
the PDCH. This is considered sub-optimal, and some BTS models offer a
direct interface by which the PCU can exchange those primitives directly
with the PHY.
The default PCU socket interface name is `/tmp/pcu_sock`, but this can
be overridden by the @pcu-socket@ VTY command in the BTS configuration
VTY node.

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

@ -0,0 +1,105 @@
== Overview
=== About this manual
This manual should help you getting started with the OsmoBTS software.
It will cover aspects of configuring and running OsmoBTS as well as some
introduction about its internal architecture and external interfaces.
=== About OsmoBTS
OsmoBTS is an implementation of a GSM BTS (Base Transceiver Station). A
BTS serves as the interface between the Um radio interface towards
phones and the wired Abis interface towards the BSC (Base Station
Controller). It also implements the network side of the Layer 2 of the
Um radio interface: The LAPDm protocol.
OsmoBTS is licensed as Free and Open Source Software (FOSS) under _GNU
AGPLv3_ <<gnu-agplv3>>. It is developed as one GSM network
infrastructure component part of the overall Osmocom project.
As perhaps the first implementation of a GSM BTS ever in the industry,
OsmoBTS is implemented in a vendor-independent way and supports a large
variety of transceiver hardware and physical layer implementations from
many vendors.
=== Credits
OsmoBTS was originally developed in 2011 by Andreas Eversberg and Harald
Welte. It has since been maintained by Harald Welte and Holger Freyther
at sysmocom.
=== OsmoBTS in the Osmocom GSM network architecture
OsmoBTS can be used in combination with the various other GSM network
elements developed under the umbrella of the Osmocom project.
Typical configurations either use OsmoBTS with OsmoBSC, or with
OsmoNITB, as can be seen in the following figures.
[[fig-gsm-classic]]
.Classic GSM archtiecture using OsmoBTS with OsmoBTS components
[graphviz]
----
digraph G {
rankdir=LR;
MS0 [label="MS"]
MS1 [label="MS"]
MS2 [label="MS"]
MS3 [label="MS"]
BTS0 [label="OsmoBTS"]
BTS1 [label="OsmoBTS"]
BSC [label="OsmoBSC"]
MSC [label="MSC/VLR"]
HLR [label="HLR/AUC"]
MS0->BTS0 [label="Um"]
MS1->BTS0 [label="Um"]
MS2->BTS1 [label="Um"]
MS3->BTS1 [label="Um"]
BTS0->BSC [label="Abis"]
BTS1->BSC [label="Abis"]
BSC->MSC [label="A"]
MSC->HLR [label="C"]
MSC->EIR [label="F"]
MSC->SMSC
}
----
[[fig-gsm-nitb]]
.GSM architecture using OsmoBTS + OsmoNITB
[graphviz]
----
digraph G {
rankdir=LR;
MS0 [label="MS"]
MS1 [label="MS"]
MS2 [label="MS"]
MS3 [label="MS"]
BTS0 [label="OsmoBTS"]
BTS1 [label="OsmoBTS"]
MS0->BTS0 [label="Um"]
MS1->BTS0 [label="Um"]
MS2->BTS1 [label="Um"]
MS3->BTS1 [label="Um"]
BTS0->BSC [label="Abis"]
BTS1->BSC [label="Abis"]
subgraph cluster_nitb {
label = "OsmoNITB";
BSC
MSC [label="MSC/VLR"]
HLR [label="HLR/AUC"]
BSC->MSC [label="A"]
MSC->HLR [label="C"]
MSC->EIR [label="F"]
MSC->SMSC;
}
}
----
If intended by the user, it is of course also possible to implement an
OsmoBTS-compatible Abis-over-IP interface in any third party BSC. The
Abis/IP interface and its protocol are documented in the _OsmoBTS
Abis Protocol Specification_ <<osmobts-abis-spec>>. However, be advised
that such a configuration is currently not officially supported by
Osmocom.

68
doc/manuals/osmobts-abis-docinfo.xml Normal file
View File

@ -0,0 +1,68 @@
<revhistory>
<revision>
<revnumber>1</revnumber>
<date>December 2015</date>
<authorinitials>NJH, HW</authorinitials>
<revremark>
Initial version, reflecting OsmoBTS master branch as on 2015-Dec-7
(commit e28a20a2d9d049cd6312e218a7646593bbc43431).
</revremark>
</revision>
<revision>
<revnumber>2</revnumber>
<date>February 2016</date>
<authorinitials>HW</authorinitials>
<revremark>
Updated version with Message Sequence Chart of OML and RSL bring-up.
</revremark>
</revision>
<revision>
<revnumber>2.1</revnumber>
<date>February 2016</date>
<authorinitials>HW</authorinitials>
<revremark>
Fix A-bis OML/RSL port number swap in message seqeuence charts.
</revremark>
</revision>
</revhistory>
<authorgroup>
<author>
<firstname>Neels</firstname>
<surname>Hofmayr</surname>
<email>nhofmayr@sysmocom.de</email>
<authorinitials>NJH</authorinitials>
<affiliation>
<shortaffil>sysmocom</shortaffil>
<orgname>sysmocom - s.f.m.c. GmbH</orgname>
<jobtitle>Senior Software Developer</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>
</authorgroup>
<copyright>
<year>2015-2016</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 no Invariant Sections, 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>
</legalnotice>

90
doc/manuals/osmobts-abis.adoc Normal file
View File

@ -0,0 +1,90 @@
OsmoBTS Abis Protocol Specification
===================================
Neels Hofmeyr <nhofmeyr@sysmocom.de>
== Introduction
This document describes the A-bis interface of *OsmoBTS*. Based on 3GPP TS
12.21 and 08.58, this document indicates which of the 3GPP specified A-bis
messages and IEs are implemented according to 3GPP specifications, which of
these are not or not fully implemented, as well as OsmoBTS-specific extensions
to the A-bis interface not specified by 3GPP.
Extensions to the A-bis interface specific to OsmoBTS are detailed in this
document. For details on the messages and IEs that comply with abovementioned
3GPP specifications, please refer to those documents.
.3GPP document versions referred to by this document
[cols="20%,80%"]
|===
|3GPP TS 08.56 | version 8.0.1 Release 1999
|3GPP TS 08.58 | version 8.6.0 Release 1999
|3GPP TS 08.60 | version 8.2.1 Release 1999
|3GPP TS 12.21 | version 8.0.0 Release 1999
|===
.IETF documents referred to by his document
[cols="20%,80%"]
|===
|IETF RFC 768 | User Datagram Protocol
|IETF RFC 791 | Internet Protocol
|IETF RFC 793 | Transmission Control Protocol
|IETF RFC 1889 | RTP: A Transport Protocol for Real-Time Applications
|IETF RFC 3551 | RTP Profle for Audio and Video Conferences with Minimal Control
|IETF RFC 4867 | RTP Payload Format and Files Storage Format for the Adaptive Multi-Rate (AMR) and Adaptive Multi-Rate Wideband (AMR-WB) Audio Codecs
|IETF RFC 5993 | RTP Payload Format for Global Systems for Mobile Communications Half Rate (GSM-HR)
|===
== Overview
The OsmoBTS A-bis interface consists of traffic management messages (RSL, Radio
Signalling Link) and network management messages (OML, Operation & Maintenance
Link), encapsulated in an IPA multiplex.
OML and RSL each use a separate TCP connection.
.TCP port numbers used by OsmoBTS Abis/IP
[options="header",width="50%",cols="35%,65%"]
|===
|TCP Port Number|Usage
|3002|A-bis OML (inside IPA multiplex)
|3003|A-bis RSL (inside IPA multiplex)
|===
Both TCP connections for OML and RSL are established in the BTS -> BSC
direction, i.e. the BTS is running as a TCP client, while the BSC is
running as a TCP server.
The BTS first establishes the TCP connection for OML. Via OML, the BSC
instructs the BTS to which IP address the RSL connection shall be
established.
.Overview of A-bis connection establishment
["mscgen"]
----
include::abis/abis-startup.msc[]
----
=== Identities
The BTS is locally configured (via administrative means, out of band of
this specification) to have a Unit ID. The Unit ID consists of three
parts:
* The Site Number
* The BTS number at the site
* The TRX number within the BTS
include::abis/ipa.adoc[]
include::abis/oml.adoc[]
include::abis/rsl.adoc[]
include::abis/rtp.adoc[]
include::../common/chapters/port_numbers.adoc[]
include::../common/chapters/glossary.adoc[]
include::../common/chapters/gfdl.adoc[]

42
doc/manuals/osmobts-usermanual-docinfo.xml Normal file
View File

@ -0,0 +1,42 @@
<revhistory>
<revision>
<revnumber>1</revnumber>
<date>January 2016</date>
<authorinitials>HW</authorinitials>
<revremark>
Initial version, reflecting OsmoBTS master branch as on FIXME
(commit FIXME).
</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>2016</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>
</legalnotice>

32
doc/manuals/osmobts-usermanual.adoc Normal file
View File

@ -0,0 +1,32 @@
OsmoBTS User Manual
===================
Harald Welte <hwelte@sysmocom.de>
include::../common/chapters/preface.adoc[]
include::chapters/overview.adoc[]
include::chapters/abis.adoc[]
include::chapters/interfaces.adoc[]
include::../common/chapters/vty.adoc[]
include::../common/chapters/logging.adoc[]
include::chapters/configuration.adoc[]
include::chapters/bts-models.adoc[]
include::chapters/architecture.adoc[]
include::../common/chapters/control_if.adoc[]
include::../common/chapters/port_numbers.adoc[]
include::../common/chapters/bibliography.adoc[]
include::../common/chapters/glossary.adoc[]
include::../common/chapters/gfdl.adoc[]