== 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 52.021 [[3gpp-ts-52-021]] (previously 3GPP TS
12.21).

==== Messages Compliant With TS 52.021

Specific limitations apply, see the linked sections.

.Messages compliant with TS 52.021
[options="header",cols="10%,10%,20%,35%,5%,20%"]
|===
| TS 52.021 § | 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
6+<| *Other Messages:*
.3+.| 8.11.1 | 0x81     | <<get_attributes>> | Get Attributes         | <- | Received
    | 8.11.3 | 0x82     | <<get_attr_resp>>  | Get Attribute Response | -> | Sent
    | 8.11.1 | 0x83     |                    | Get Attributes Nack    | -> | Sent
|===


==== Messages Specific to OsmoBTS

.Messages specific to OsmoBTS, not found in 3GPP TS 52.021
[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 52.021 messages not implemented by OsmoBTS
[options="header",cols="10%,10%,80%"]
|===
| TS 52.021 § | 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:*
.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 52.021 § 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
52.021, 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 52.021 § | 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 52.021, 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 52.021 § | IE Name | Handling
| 9.4.5 | ARFCN List | ignored
|===


[[set_chan_attr]]
==== Set Channel Attributes

This message conforms to 3GPP TS 52.021, with the following limitation: the
following 3GPP TS 52.021 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 52.021 § | 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 52.021. 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 52.021 9.1 | M | V | 1
| Object Class | 3GPP TS 52.021 9.2 | M | V | 1
| Object Instance | 3GPP TS 52.021 9.3 | M | V | 3
| Operational State | 3GPP TS 52.021 9.4.38 | O | TV | 2
| Availability Status | 3GPP TS 52.021 9.4.7 | O | TL16V (with length of 1) | 3
|===

[[chg_adm_state]]
==== Change Administrative State

This message is compliant with 3GPP TS 52.021 § 8.8.5. It applies to all of the
Object Classes defined in 3GPP TS 52.021 § 9.2 as well as
<<addnl_obj_classes>>.

[[opstart]]
==== Opstart

This message is compliant with 3GPP TS 52.021 § 8.9.2. It applies to all of the
Object Classes defined in 3GPP TS 52.021 § 9.2 as well as
<<addnl_obj_classes>>.

[[get_attributes]]
==== Get Attributes

This message is compliant with 3GPP TS 52.021 § 8.11.1.

For a list of supported attributes, see <<get_attr_resp>>.

[[get_attr_resp]]
==== Get Attribute Response

This message is compliant with 3GPP TS 52.021 § 8.11.3.

The following attributes are provided by OsmoBTS:

[options="header"]
|===
| 3GPP TS 52.021 chapter | description      | see
| 9.4.61                 | SW Configuration | <<NM_ATT_SW_CONFIG>>
| 9.4.30                 | Manufacturer Id  | <<NM_ATT_MANUF_ID>>
|===

=== 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 52.021 9.1 | M | V | 1
| Object Class | 3GPP TS 52.021 9.2 | M | V | 1
| Object Instance | 3GPP TS 52.021 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 52.021 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 52.021 9.1 | M | V | 1
| Object Class | 3GPP TS 52.021 9.2 | M | V | 1
| Object Instance | 3GPP TS 52.021 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 52.021 9.1 | M | V | 1
| Object Class | 3GPP TS 52.021 9.2 | M | V | 1
| Object Instance | 3GPP TS 52.021 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 52.021 9.1 | M | V | 1
| Object Class | 3GPP TS 52.021 9.2 | M | V | 1
| Object Instance | 3GPP TS 52.021 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 52.021 specified in more detail.

==== IEs Conforming to TS 52.021

The following Information Elements are accepted by OsmoBTS.

IEs marked __ignored__ may be sent to OsmoBTS without causing error
conditions. These IEs are skipped during message parsing and are never
evaluated.

IEs marked __ignored__ and additionally marked as being received by OsmoBTS
(<-) are in fact parsed and their values are stored by OsmoBTS, but these
stored items are currently not used in the OsmoBTS code base.

.IEs conforming to TS 52.021
[options="header",cols="5%,10%,40%,5%,40%"]
|===
| tag (hex) | TS 52.021 § | 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  | <- |
| 0x19 | 9.4.25 | Interference level Boundaries  | <- |
| 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  | -> | Sent, see <<NM_ATT_SW_CONFIG>>
| 0x43 | 9.4.63 | Perceived Severity  |  | _ignored_
| 0x44 | 9.4.64 | Get Attribute Response Info  | -> | Sent, see <<NM_ATT_MANUF_ID>>
| 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 52.021

.IEs not conforming to TS 52.021
[options="header",cols="5%,10%,30%,55%"]
|===
| tag (hex) | TS 52.021 § | 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 52.021 Chapter 9.4.

All of these additional IEs are _received_ by OsmoBTS.

These attributes are not used by OsmoBTS, but
simply passed to OsmoPCU connected to the PCU socket.

.Additional IEs handled by OsmoBTS but not defined in TS 52.021
[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 52.021 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 52.021 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 | ip.access style Dynamic TCH/F / PDCH
| 0x81 | Reserved for Dynamic TCH/F / TCH/H
| 0x90 | Osmocom style Dynamic TCH/F / TCH/H / PDCH
|===

The _Reserved_ combinations are not actually supported/implemented
yet, but merely reserved for such functionality, if it is eventually
implemented.

For more information on how the different dynamic channel combinations
work, please see the <<rsl-dynamic-channels>>.

[[ie_conn_fail_crit]]
==== Connection Failure Criterion

3GPP TS 52.021 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 52.021.


[[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 consists of a single octet
encoding the GPRS Routing Area Code.

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.

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.

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 consists of an array of 7 octets,
each describing one GPRS NS related timer:

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.

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

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.

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.

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

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

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

This attribute is not used by OsmoBTS, but
simply passed to OsmoPCU connected to the PCU socket.

[[NM_ATT_SW_CONFIG]]
==== SW Configuration

The SW Configuration IE is compliant with 3GPP TS 52.021 9.4.61: it contains a
number of SW Description IEs (9.4.62).


.Coding of SW Configuration IE
[options="header",cols="20%,80%"]
|===
| octet | value
| 1     | NM_ATT_SW_CONFIG IEI (0x41)
| 2-3   | length of value part
| 4     | NM_ATT_SW_DESCR IEI (0x42)
| 5     | NM_ATT_FILE_ID IEI (0x12)
| 6-7   | length of file name
| 8-N   | ASCII coded file name (without terminating nul)
| N+1   | NM_ATT_FILE_VERSION IEI (0x13)
| N+2 - N+3 | length of file content
| N+4 - M | file content
| M+1   | NM_ATT_SW_DESCR IEI (0x42)
| M+2   | NM_ATT_FILE_ID IEI (0x12)
2+| ...
|===

.File names and content sent in the SW Configuration IE
[options="header",cols="20%,80%"]
|===
| file name | content
| 'osmobts' | ASCII coded OsmoBTS version number like "1.2.3" or "1.2.3.4-abcd"
| 'BTS_TYPE_VARIANT' | one of "osmo-bts-lc15", "osmo-bts-oc2g", "osmo-bts-octphy",
                       "osmo-bts-omldummy", "osmo-bts-sysmo", "osmo-bts-trx", "osmo-bts-virtual"
| 'BTS_SUB_MODEL' | This file may be omitted; if present, may contain an ASCII
                    coded model number like "sysmoBTS 1002"
|===


[[NM_ATT_MANUF_ID]]
==== Manufacturer Id

The coding of the Manufacturer Id attribute is a sequence of bit flags (a bit
vector), where a zero flag indicates absence and a set flag indicates presence
of a specific BTS feature.

The number of flags transmitted depends on the software version of OsmoBTS and
the BTS backend in use. More flags may be added in the future. The flag bits
transmitted are followed by zero bits up to the next full octet boundary.

These features are currently defined:

.coding of BTS feature flags sent in the Manufacturer Id attribute
[options="header",cols="5%,5%,30%,60%"]
|===
| octet  | bit | feature name | description
.8+.|  0 |  7  | HSCSD | High-Speed Circuit-Switched Data
         |  6  | GPRS | General Packet Radio Service
         |  5  | EGPRS | Enhanced GPRS (EDGE)
         |  4  | ECSD | Enhanced Circuit-Switched Data
         |  3  | HOPPING | Frequency Hopping
         |  2  | MULTI_TSC | Multi-TSC
         |  1  | OML_ALERTS | OML Alerts
         |  0  | AGCH_PCH_PROP | AGCH/PCH proportional allocation
.8+.|  1 |  7  | CBCH | Cell Broadcast Channel
         |  6  | SPEECH_F_V1 | Fullrate speech V1
         |  5  | SPEECH_H_V1 | Halfrate speech V1
         |  4  | SPEECH_F_EFR | Fullrate speech EFR
         |  3  | SPEECH_F_AMR | Fullrate speech AMR
         |  2  | SPEECH_H_AMR | Halfrate speech AMR
         |  1  | ETWS_PN | ETWS Primary Notification via PCH
         |  0  | PAGING_COORDINATION | BSS Paging Coordination
.8+.|  2 |  7  | IPV6_NSVC | NSVC IPv6
         |  6  | ACCH_REP | FACCH/SACCH Repetition
         |  5  | CCN | Cell Change Notification
         |  4  | VAMOS | Voice services over Adaptive Multi-user channels on One Slot
         |  3  2.4+.| reserved for future use, sent as zero
         |  2
         |  1
         |  0
|===


=== 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 52.021 as
amended by 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 not modular
and thus all MOs start with the software fully activated.  In effect, 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[]
----

The Site Manager MO does not depend on other MOs, nor does it have an
Administrative state (__Locked/Unlocked__), thus it immediately commences in
the __Enabled__ state.

==== BTS MO Initialization

.A-bis OML Initialization of BTS MO
["mscgen"]
----
include::oml-mo-bts.msc[]
----

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


==== Complete BTS Initialization Procedure

Some of below steps are optional, as is their detailed ordering.  In
practice, 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 shown 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, and
. 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, and
.. 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[]
----

<<oml-msc-2>> shows:

. 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 as
  well as software activation.

<<oml-msc-3>> shows:

. 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 takes place for each of the 'Channel' MOs:
.. Set the Channel Attributes (such as channel combination),
.. OPSTART,
.. change the Administrative State to Unlocked,
.. followed by a State Change Event Report with the new state.
. After all 'Channel' MOs are initialized, the Radio Carrier goes through
  a similar procedure:
.. Set attributes,
.. OPSTART,
.. change Administrative State to Unlocked,
.. followed by a 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.