diff options
Diffstat (limited to 'doc/manuals/chapters')
| -rw-r--r-- | doc/manuals/chapters/bts-examples.adoc | 281 | ||||
| -rw-r--r-- | doc/manuals/chapters/control.adoc | 100 | ||||
| -rw-r--r-- | doc/manuals/chapters/counters.adoc | 4 | ||||
| -rw-r--r-- | doc/manuals/chapters/counters_generated.adoc | 76 | ||||
| -rw-r--r-- | doc/manuals/chapters/handover.adoc | 577 | ||||
| -rw-r--r-- | doc/manuals/chapters/handover_inter_bsc.dot | 35 | ||||
| -rw-r--r-- | doc/manuals/chapters/handover_intra_bsc.dot | 31 | ||||
| -rw-r--r-- | doc/manuals/chapters/overview.adoc | 174 | ||||
| -rw-r--r-- | doc/manuals/chapters/running.adoc | 42 |
9 files changed, 1320 insertions, 0 deletions
diff --git a/doc/manuals/chapters/bts-examples.adoc b/doc/manuals/chapters/bts-examples.adoc new file mode 100644 index 000000000..b15fb9921 --- /dev/null +++ b/doc/manuals/chapters/bts-examples.adoc @@ -0,0 +1,281 @@ +[[bts-examples]] +== OsmoNITB example configuration files + +The `openbsc/doc/examples/osmo-nitb` directory in the OpenBSC source +tree contains a collection of example configuration files, sorted by BTS +type. + +This chapter is illustrating some excerpts from those examples + +[[bts_example_bs11]] +=== Example configuration for OsmoNITB with one dual-TRX BS-11 + +.OsmoNITB with BS11, 2 TRX, no frequency hopping +==== + +---- +e1_input + e1_line 0 driver misdn +network + network country code 1 + mobile network code 1 + short name OpenBSC + long name OpenBSC + timer t3101 10 + timer t3113 60 + bts 0 + type bs11 <1> + band GSM900 + cell_identity 1 + location_area_code 1 + training_sequence_code 7 + base_station_id_code 63 + oml e1 line 0 timeslot 1 sub-slot full <2> + oml e1 tei 25 <3> + trx 0 + arfcn 121 + max_power_red 0 + rsl e1 line 0 timeslot 1 sub-slot full <4> + rsl e1 tei 1 <5> + timeslot 0 + phys_chan_config CCCH+SDCCH4 + e1 line 0 timeslot 1 sub-slot full + timeslot 1 + phys_chan_config TCH/F + e1 line 0 timeslot 2 sub-slot 1 <6> + timeslot 2 + phys_chan_config TCH/F + e1 line 0 timeslot 2 sub-slot 2 + timeslot 3 + phys_chan_config TCH/F + e1 line 0 timeslot 2 sub-slot 3 + timeslot 4 + phys_chan_config TCH/F + e1 line 0 timeslot 3 sub-slot 0 + timeslot 5 + phys_chan_config TCH/F + e1 line 0 timeslot 3 sub-slot 1 + timeslot 6 + phys_chan_config TCH/F + e1 line 0 timeslot 3 sub-slot 2 + timeslot 7 + phys_chan_config TCH/F + e1 line 0 timeslot 3 sub-slot 3 + trx 1 + arfcn 123 + max_power_red 0 + rsl e1 line 0 timeslot 1 sub-slot full <4> + rsl e1 tei 2 <5> + timeslot 0 + phys_chan_config TCH/F + e1 line 0 timeslot 4 sub-slot 0 <6> + timeslot 1 + phys_chan_config TCH/F + e1 line 0 timeslot 4 sub-slot 1 + timeslot 2 + phys_chan_config TCH/F + e1 line 0 timeslot 4 sub-slot 2 + timeslot 3 + phys_chan_config TCH/F + e1 line 0 timeslot 4 sub-slot 3 + timeslot 4 + phys_chan_config TCH/F + e1 line 0 timeslot 5 sub-slot 0 + timeslot 5 + phys_chan_config TCH/F + e1 line 0 timeslot 5 sub-slot 1 + timeslot 6 + phys_chan_config TCH/F + e1 line 0 timeslot 5 sub-slot 2 + timeslot 7 + phys_chan_config TCH/F + e1 line 0 timeslot 5 sub-slot 3 +---- +==== + +<1> The BTS type must be set to __bs11__ +<2> The OML E1 timeslot needs to be identical with what was on the BTS side using LMT. +<3> The OML TEI value needs to be identical with what was configured on the BTS side using LMT. +<4> The RSL E1 timeslot can be identical for all TRX. +<5> The RSL TEI values __must__ be different if multiple TRX share one E1 signalling timeslot. +<6> The TCH all need to be allocated one 16k sub-slot on the E1 + +[[bts_example_nbts]] +=== Example configuration for OsmoNITB with one single-TRX nanoBTS + +.OsmoNITB with one single-TRX nanoBTS +==== + +---- +e1_input + e1_line 0 driver ipa <1> +network + network country code 1 + mobile network code 1 + short name OpenBSC + long name OpenBSC + auth policy closed + location updating reject cause 13 + encryption a5 0 + neci 1 + rrlp mode none + mm info 1 + handover 0 + bts 0 + type nanobts <2> + band DCS1800 <3> + cell_identity 0 + location_area_code 1 + training_sequence_code 7 + base_station_id_code 63 + ms max power 15 + cell reselection hysteresis 4 + rxlev access min 0 + channel allocator ascending + rach tx integer 9 + rach max transmission 7 + ip.access unit_id 1801 0 <4> + oml ip.access stream_id 255 line 0 + gprs mode none + trx 0 + rf_locked 0 + arfcn 871 <5> + nominal power 23 + max_power_red 20 <6> + rsl e1 tei 0 + timeslot 0 + phys_chan_config CCCH+SDCCH4 + timeslot 1 + phys_chan_config SDCCH8 + timeslot 2 + phys_chan_config TCH/F + timeslot 3 + phys_chan_config TCH/F + timeslot 4 + phys_chan_config TCH/F + timeslot 5 + phys_chan_config TCH/F + timeslot 6 + phys_chan_config TCH/F + timeslot 7 + phys_chan_config TCH/F +---- +==== + +<1> You have to configure one virtual E1 line with the + IPA driver in order to use Abis/IP. One e1_line is + sufficient for any number of A-bis/IP BTSs, there is no + limit like in physical E1 lines. +<2> The BTS type must be set using `type nanobts` +<3> The GSM band must be set according to the BTS hardware. +<4> The IPA Unit ID parameter must be set to what has been configured on + the BTS side using the __BTS Manager__ or `ipaccess-config`. +<5> The ARFCN of the BTS. +<6> All known nanoBTS units have a nominal transmit power of 23 dBm. If + a `max_power_red` of 20 (dB) is configured, the resulting output + power at the BTS Tx port is 23 - 20 = 3 dBm. + +[NOTE] +==== +The `nominal_power` setting does __not__ influence the transmitted power +to the BTS! It is a setting by which the system administrator tells the +BSC about the nominal output power of the BTS. The BSC uses this as +basis for calculations. +==== + + +[[bts_example_nbts_multi]] +=== Example configuration for OsmoNITB with multi-TRX nanoBTS + +.OsmoNITB configured for dual-TRX (stacked) nanoBTS +==== + +---- +e1_input + e1_line 0 driver ipa +network + network country code 1 + mobile network code 1 + short name OpenBSC + long name OpenBSC + auth policy closed + location updating reject cause 13 + encryption a5 0 + neci 1 + rrlp mode none + mm info 0 + handover 0 + bts 0 + type nanobts + band DCS1800 + cell_identity 0 + location_area_code 1 + training_sequence_code 7 + base_station_id_code 63 + ms max power 15 + cell reselection hysteresis 4 + rxlev access min 0 + channel allocator ascending + rach tx integer 9 + rach max transmission 7 + ip.access unit_id 1800 0 <1> + oml ip.access stream_id 255 line 0 + gprs mode none + trx 0 + rf_locked 0 + arfcn 871 + nominal power 23 + max_power_red 0 + rsl e1 tei 0 + timeslot 0 + phys_chan_config CCCH+SDCCH4 + timeslot 1 + phys_chan_config SDCCH8 + timeslot 2 + phys_chan_config TCH/F + timeslot 3 + phys_chan_config TCH/F + timeslot 4 + phys_chan_config TCH/F + timeslot 5 + phys_chan_config TCH/F + timeslot 6 + phys_chan_config TCH/F + timeslot 7 + phys_chan_config TCH/F + trx 1 + rf_locked 0 + arfcn 873 + nominal power 23 + max_power_red 0 + rsl e1 tei 0 + timeslot 0 + phys_chan_config SDCCH8 + timeslot 1 + phys_chan_config TCH/F + timeslot 2 + phys_chan_config TCH/F + timeslot 3 + phys_chan_config TCH/F + timeslot 4 + phys_chan_config TCH/F + timeslot 5 + phys_chan_config TCH/F + timeslot 6 + phys_chan_config TCH/F + timeslot 7 + phys_chan_config TCH/F +---- +==== + +<1> In this example, the IPA Unit ID is specified as `1800 0`. Thus, the + first nanoBTS unit (`trx 0`) needs to be configured to 1800/0/0 and + the second nanoBTS unit (`trx 1`) needs to be configured to 1800/0/1. + You can configure the BTS unit IDs using the `ipaccess-config` + utility included in OpenBSC. + +[NOTE] +==== +For building a multi-TRX setup, you also need to connect the TIB cables +between the two nanoBTS units, as well as the coaxial/RF AUX cabling. +==== diff --git a/doc/manuals/chapters/control.adoc b/doc/manuals/chapters/control.adoc new file mode 100644 index 000000000..327e5b4af --- /dev/null +++ b/doc/manuals/chapters/control.adoc @@ -0,0 +1,100 @@ +[[control]] +== Control interface + +The actual protocol is described in <<common-control-if>>, the variables +common to all programs using it are described in <<ctrl_common_vars>>. Here we +describe variables specific to OsmoBSC. The commands starting with prefix +"bts.N." are specific to a certain BTS so N have to be replaced with BTS +number when issuing command e. g. "bts.1.channel-load". Similarly the +TRX-specific commands are additionally prefixed with TRX number e. g. +"bts.1.trx.2.arfcn". + +.Variables available over control interface +[options="header",width="100%",cols="20%,5%,5%,50%,20%"] +|=== +|Name|Access|Trap|Value|Comment +|msc_connection_status|RO|Yes|"connected", "disconnected"|Indicate the status of connection to MSC. +|bts_connection_status|RO|Yes|"connected", "disconnected"|Indicate the status of connection to BTS. +|location|RW|Yes|"<unixtime>,(invalid\|fix2d\|fix3d),<lat>,<lon>,<height>"|Set/Get location data. +|timezone|RW|No|"<hours>,<mins>,<dst>", "off"|-19 \<= hours \<= 19, mins in {0, 15, 30, 45}, and 0 \<= dst \<= 2 +|apply-configuration|WO|No|"restart"|Restart all BTSes. +|mnc|RW|No|"<mnc>"|Set/Get MNC (value between (0, 999)). +|mcc|RW|No|"<mcc>"|Set/Get MCC (value between (1, 999)). +|short-name|RW|No|"<name>"|Set/Get network's short name. +|long-name|RW|No|"<name>"|Set/Get network's long name. +|mcc-mnc-apply|WO|No|"<mcc>,<mnc>"|Apply new MCC/MNC values if different from currently used one. +|notification|WO|Yes|Arbitrary value| See <<notif>> for details. +|inform-msc-v1|WO|Yes|Arbitrary value| See <<infomsc>> for details. +|ussd-notify-v1|WO|No|"<cic>,<alert>,<text>"| See <<ussdnot>> for details. +|rf_locked|RW|No|"0","1"|See <<rfl>> for details. +|number-of-bts|RO|No|"<num>"|Get number of configured BTS. +|bts.N.location-area-code|RW|No|"<lac>"|Set/Get LAC (value between (0, 65535)). +|bts.N.cell-identity|RW|No|"<id>"|Set/Get Cell Identity (value between (0, 65535)). +|bts.N.apply-configuration|WO|No|Ignored|Restart BTS via OML. +|bts.N.send-new-system-informations|WO|No|Ignored|Regenerate System Information messages for given BTS. +|bts.N.channel-load|RO|No|"<name>,<used>,<total>"|See <<chanlo>> for details. +|bts.N.oml-connection-state|RO|No|"connected", "disconnected", "degraded"|Indicate the status of OML connection of BTS. +|bts.N.oml-uptime|RO|No|<uptime>|Return OML link uptime in seconds. +|bts.N.gprs-mode|RW|No|"<mode>"|See <<gprsm>> for details. +|bts.N.rf_state|RO|No|"<oper>,<admin>,<pol>"|See <<rfs>> for details. +|bts.N.trx.M.arfcn|RW|No|"<arfcn>"|Set/Get ARFCN (value between (0, 1023)). +|bts.N.trx.M.max-power-reduction|RW|No|"<mpr>"|See <<mpr>> for details. +|=== + +[[notif]] +=== notification + +Setting this variable initiate TRAP "notification" to all the clients connected +to control interface with the value supplied in SET operation. This is not +intended to be used outside of local systems. + +[[infomsc]] +=== inform-msc-v1 + +Setting this variable initiate TRAP "inform-msc-v1" to all connected MSCs +control interfaces with the value supplied in SET operation. + +[[ussdnot]] +=== ussd-notify-v1 + +Setting this variable will send USSD Notify message to subscriber specified in +command parameters with the text specified in command parameters. + +[[chanlo]] +=== channel-load + +Obtain channel load for given BTS. Returns concatenated set of triplets +("<name>,<used>,<total>") for all channel types configured on the BTS. The +"<name>" is the channel type. The "<used>" is the number of channels of that +type currently in use. The "<total>" is the number of channels of that type +configured on the BTS. + +[[gprsm]] +=== gprs-mode + +Set/Get the GPRS mode of the BTS. One of the following is +accepted/returned: "none", "gprs", "egprs". + +[[rfs]] +=== rf_state + +Following triplet is returned: "<oper>,<admin>,<pol>". The "<oper>" might be +"operational" or "inoperational" representing different operational states. The +"<admin>" might be "locked" or "unlocked" representing administrative status. +The "<pol>" might be "off", "on", "grace" or "unknown" representing different +RF policies. + +[[rfl]] +=== rf_locked + +Set/Get RF locked status. The GET operation will return either "0" or "1" +depending on the RF lock status. The SET operation will set RF lock status if +RF Ctrl is enabled in the BSC Configuration. + +[[mpr]] +=== max-power-reduction + +Set/Get the value of maximum power reduction. Even values between 0 and 22 are +accepted. + +FIXME: add variables defined in src/ctrl/control_if.c? diff --git a/doc/manuals/chapters/counters.adoc b/doc/manuals/chapters/counters.adoc new file mode 100644 index 000000000..7fbb10c6f --- /dev/null +++ b/doc/manuals/chapters/counters.adoc @@ -0,0 +1,4 @@ +[[counters]] +== Counters + +include::./counters_generated.adoc[] diff --git a/doc/manuals/chapters/counters_generated.adoc b/doc/manuals/chapters/counters_generated.adoc new file mode 100644 index 000000000..d55df072f --- /dev/null +++ b/doc/manuals/chapters/counters_generated.adoc @@ -0,0 +1,76 @@ +// autogenerated by show asciidoc counters +These counters and their description based on OsmoBSC (OsmoBSC). + +// generating tables for rate_ctr_group +// rate_ctr_group table E1 Input subsystem +.e1inp - E1 Input subsystem +[options="header"] +|=== +| Name | Reference | Description +| hdlc:abort | <<e1inp_hdlc:abort>> | HDLC abort +| hdlc:bad_fcs | <<e1inp_hdlc:bad_fcs>> | HLDC Bad FCS +| hdlc:overrun | <<e1inp_hdlc:overrun>> | HDLC Overrun +| alarm | <<e1inp_alarm>> | Alarm +| removed | <<e1inp_removed>> | Line removed +|=== +// rate_ctr_group table base station controller +.bsc - base station controller +[options="header"] +|=== +| Name | Reference | Description +| chreq:total | <<bsc_chreq:total>> | Received channel requests. +| chreq:no_channel | <<bsc_chreq:no_channel>> | Sent to MS no channel available. +| handover:attempted | <<bsc_handover:attempted>> | Received handover attempts. +| handover:no_channel | <<bsc_handover:no_channel>> | Sent no channel available responses. +| handover:timeout | <<bsc_handover:timeout>> | Count the amount of timeouts of timer T3103. +| handover:completed | <<bsc_handover:completed>> | Received handover completed. +| handover:failed | <<bsc_handover:failed>> | Receive HO FAIL messages. +| paging:attempted | <<bsc_paging:attempted>> | Paging attempts for a MS. +| paging:detached | <<bsc_paging:detached>> | Counts the amount of paging attempts which couldn't sent out any paging request because no responsible bts found. +| paging:completed | <<bsc_paging:completed>> | Paging successful completed. +| paging:expired | <<bsc_paging:expired>> | Paging Request expired because of timeout T3113. +| chan:rf_fail | <<bsc_chan:rf_fail>> | Received a RF failure indication from BTS. +| chan:rll_err | <<bsc_chan:rll_err>> | Received a RLL failure with T200 cause from BTS. +| bts:oml_fail | <<bsc_bts:oml_fail>> | Received a TEI down on a OML link. +| bts:rsl_fail | <<bsc_bts:rsl_fail>> | Received a TEI down on a OML link. +| bts:codec_amr_f | <<bsc_bts:codec_amr_f>> | Count the usage of AMR/F codec by channel mode requested. +| bts:codec_amr_h | <<bsc_bts:codec_amr_h>> | Count the usage of AMR/H codec by channel mode requested. +| bts:codec_efr | <<bsc_bts:codec_efr>> | Count the usage of EFR codec by channel mode requested. +| bts:codec_fr | <<bsc_bts:codec_fr>> | Count the usage of FR codec by channel mode requested. +| bts:codec_hr | <<bsc_bts:codec_hr>> | Count the usage of HR codec by channel mode requested. +|=== +// rate_ctr_group table mobile switching center +.msc - mobile switching center +[options="header"] +|=== +| Name | Reference | Description +| loc_update_type:attach | <<msc_loc_update_type:attach>> | Received location update imsi attach requests. +| loc_update_type:normal | <<msc_loc_update_type:normal>> | Received location update normal requests. +| loc_update_type:periodic | <<msc_loc_update_type:periodic>> | Received location update periodic requests. +| loc_update_type:detach | <<msc_loc_update_type:detach>> | Received location update detach indication. +| loc_update_resp:failed | <<msc_loc_update_resp:failed>> | Rejected location updates. +| loc_update_resp:completed | <<msc_loc_update_resp:completed>> | Successful location updates. +| sms:submitted | <<msc_sms:submitted>> | Received a RPDU from a MS (MO). +| sms:no_receiver | <<msc_sms:no_receiver>> | Counts SMS which couldn't routed because no receiver found. +| sms:delivered | <<msc_sms:delivered>> | Global SMS Deliver attempts. +| sms:rp_err_mem | <<msc_sms:rp_err_mem>> | CAUSE_MT_MEM_EXCEEDED errors of MS responses on a sms deliver attempt. +| sms:rp_err_other | <<msc_sms:rp_err_other>> | Other error of MS responses on a sms delive attempt. +| sms:deliver_unknown_error | <<msc_sms:deliver_unknown_error>> | Unknown error occured during sms delivery. +| call:mo_setup | <<msc_call:mo_setup>> | Received setup requests from a MS to init a MO call. +| call:mo_connect_ack | <<msc_call:mo_connect_ack>> | Received a connect ack from MS of a MO call. Call is now succesful connected up. +| call:mt_setup | <<msc_call:mt_setup>> | Sent setup requests to the MS (MT). +| call:mt_connect | <<msc_call:mt_connect>> | Sent a connect to the MS (MT). +| call:active | <<msc_call:active>> | Count total amount of calls that ever reached active state. +| call:complete | <<msc_call:complete>> | Count total amount of calls which got terminated by disconnect req or ind after reaching active state. +| call:incomplete | <<msc_call:incomplete>> | Count total amount of call which got terminated by any other reason after reaching active state. +|=== +// generating tables for osmo_stat_items +// generating tables for osmo_counters +// ungrouped osmo_counters +.ungrouped osmo counters +[options="header"] +|=== +| Name | Reference | Description +| msc.active_calls | <<ungroup_counter_msc.active_calls>> | +|=== + diff --git a/doc/manuals/chapters/handover.adoc b/doc/manuals/chapters/handover.adoc new file mode 100644 index 000000000..297eafc1f --- /dev/null +++ b/doc/manuals/chapters/handover.adoc @@ -0,0 +1,577 @@ +== Handover + +Handover is the process of moving a continuously used channel (lchan) from one +cell to another. Usually, that is an ongoing call, so that phones are able to +move across cell coverage areas without interrupting the voice transmission. + +A handover can + +- stay within one given cell (intra-cell, i.e. simply a new RR Assignment Command); +- occur between two cells that belong to the same BSS (intra-BSC, via RR Handover Command); +- cross BSS boundaries (inter-BSC, via BSSMAP handover procedures); +- move to another MSC (inter-MSC, inter-PLMN); +- move to another RAN type, e.g. from 2G to 3G (inter-RAT, inter-Radio-Access-Technology). + +The physical distance is by definition always very near, but handover +negotiation may range from being invisible to the MSC all the way to +orchestrating completely separate RAN stacks. + +OsmoBSC currently supports handover within one BSS and between separate BSS. +Whether inter-MSC is supported depends on the MSC implementation (to the BSC, +inter-MSC handover looks identical to inter-BSC handover). Inter-RAT handover +is currently not implemented. + +At the time of writing, OsmoMSC's inter-BSC handover support is not complete +yet, so OsmoBSC can perform handover between separate BSS only in conjunction +with a 3rd party MSC implementation. + +.Handover support in Osmocom at the time of writing +[cols="^,^,^,^,^"] +|==== +| | intra-BSC HO (local BSS) | inter-BSC HO (remote BSS) | inter-MSC HO | inter-RAT HO +| OsmoBSC | rxlev, load-based | rxlev | (planned) | - +| OsmoMSC | (not involved, except for codec changes) | (planned) | (planned) | - +|==== + + +=== How Handover Works + +This chapter generally explains handover operations between 2G cells. + +==== Internal / Intra-BSC Handover + +The BSS is configured to know which cell is physically adjacent to which other +cells, its "neighbors". On the MS/BTS/BSS level, individual cells are +identified by ARFCN+BSIC (frequency + 6-bit identification code). + +Each BTS is told by the BSC which cells identified by ARFCN+BSIC are its +adjacent cells. Via System Information, each MS receives a list of these +ARFCN+BSIC, and the MS then return measurements of reception levels. + +The BSC is the point of decision whether to do handover or not. This can be a +hugely complex combination of heuristics, knowledge of cell load and codec +capabilites. The most important indicator for handover though is: does an MS +report a neighbor with a better signal than the current cell? See +<<intra_bsc_ho_dot>>. + +[[intra_bsc_ho_dot]] +.Intra-BSC Handover stays within the BSS (shows steps only up to activation of the new lchan -- this would be followed by an RR Handover Command, RACH causing Handover Detection, Handover Complete, ...) +[graphviz] +---- +include::handover_intra_bsc.dot[] +---- + +If the BSC sees the need for handover, it will: + +- activate a new lchan (with a handover reference ID), +- send an RR Handover Command to the current lchan, and +- wait for the MS to send a Handover RACH to the new lchan ("Handover Detect"). +- The RTP stream then is switched over to the new lchan, +- an RSL Establish Indication is expected on the new lchan, +- and the old lchan is released. + +Should handover fail at any point, e.g. the new lchan never receives a RACH, or +the MS reports a Handover Failure, then the new lchan is simply released again, +and the old lchan remains in use. If the RTP stream has already been switched +over to the new lchan, it may actually be switched back to the old lchan. + +This is simple enough if the new cell is managed by the same BSC: the OsmoMGW +is simply instructed to relay the BTS-side of the RTP stream to another IP +address and port, and the BSC continues to forward DTAP to the MSC +transparently. The operation happens completely within the BSS. If the voice +codec has remained unchanged, the MSC/MNCC may not even be notified that +anything has happened at all. + +==== External / Inter-BSC Handover + +If the adjacent target cell belongs to a different BSS, the RR procedure for +handover remains the same, but we need to tell the _remote_ BSC to allocate the +new lchan. + +The only way to reach the remote BSC is via the MSC, so the MSC must be able +to: + +- identify which other BSC we want to talk to, +- forward various BSSMAP Handover messages between old and new BSC, +- redirect the core-side RTP stream to the new BSS at the appropriate time, +- and must finally BSSMAP Clear the connection to the old BSS to conclude the + inter-BSC handover. + +[[inter_bsc_ho_dot]] +.Inter-BSC Handover requires the MSC to relay between two BSCs (shows steps only up to the BSSMAP Handover Command -- this would be followed by an RR Handover Command, RACH causing Handover Detection, Handover Complete, ...) +[graphviz] +---- +include::handover_inter_bsc.dot[] +---- + +The first part, identifying the remote BSC, is not as trivial as it sounds: as +mentioned above, on the level of cell information seen by BTS and MS, the +neighbor cells are identified by ARFCN+BSIC. However, on the A-interface and in +the MSC, there is no knowledge of ARFCN+BSIC configurations, and instead each +cell is identified by a LAC and CI (Location Area Code and Cell Identifier). + +NOTE: There are several different cell identification types on the A-interface: +from Cell Global Identifier (MCC+MNC+LAC+CI) down to only LAC. OsmoBSC supports +most of these (see <<neighbor_conf_list>>). For simplicity, this description +focuses on LAC+CI identification. + +The most obvious reason for using LAC+CI is that identical ARFCN+BSIC are +typically re-used across many cells of the same network operator: an operator +will have only very few ARFCNs available, and the 6bit BSIC opens only a very +limited range of distinction between cells. As long as each cell has no more +than one neighbor per given ARFCN+BSIC, these values can be re-used any number +of times across a network, and even between cells managed by one and the same +BSC. + +The consequence of this is that + +- the BSC needs to know which remote-BSS cells' ARFCN+BSIC correspond to + exactly which global LAC+CI, and +- the MSC needs to know which LAC+CI are managed by which BSC. + +In other words, each BSC requires prior knowledge about the cell configuration +of its remote-BSS neighbor cells, and the MSC requires prior knowledge about +each BSC's cell identifiers; i.e. these config items are spread reduntantly. + +=== Configuring Neighbors + +The most important step to enable handover in OsmoBSC is to configure each cell +with the ARFCN+BSIC identities of its adjacent neighbors -- both local-BSS and +remote-BSS. + +For a long time, OsmoBSC has offered configuration to manually enter the +ARFCN+BSIC sent out as neighbors on various System Information messages (all +`neighbor-list` related commands). This is still possible, however, +particularly for re-using ARFCN+BSIC within one BSS, this method will not work +well. + +With the addition of inter-BSC handover support, the new `neighbor` config item +has been added to the `bts` config, to maintain explicit cell-to-cell neighbor +relations, with the possibility to re-use ARFCN+BSIC in each cell. + +It is recommended to completely replace `neighbor-list` configurations with the +new `neighbor` configuration described below. + +[[neighbor_conf_list]] +.Overview of neighbor configuration on the `bts` config node +[frame="none",grid="none",cols="^10%,^10%,80%"] +|==== +| Local | Remote BSS | +| ✓ | | neighbor bts 5 +| ✓ | | neighbor lac 200 +| ✓ | | neighbor lac-ci 200 3 +| ✓ | | neighbor cgi 001 01 200 3 +| ✓ | ✓ | neighbor lac 200 arfcn 123 bsic 1 +| ✓ | ✓ | neighbor lac-ci 200 3 arfcn 123 bsic 1 +| ✓ | ✓ | neighbor cgi 001 01 200 3 arfcn 123 bsic 1 +|==== + +==== Default: All Local Cells are Neighbors + +For historical reasons, the default behavior of OsmoBSC is to add all local-BSS cells as neighbors. To +maintain a backwards compatible configuration file format, this is still the case: as soon as no explicit +neighbor cell is configured with a `neighbor` command (either none was configured, or all configured +neighbors have been removed again), a cell automatically lists all of the local-BSS cells as neighbors. +These are implicit mappings in terms of the legacy neighbor configuration scheme, and re-using ARFCN+BSIC +combinations within a BSS will not work well this way. + +As soon as the first explicit neighbor relation is added to a cell, the legacy behavior is switched off, +and only explicit neighbors are in effect. + +NOTE: If a cell is required to not have any neighbors, it is recommended to rather switch off handover +for that cell with `handover 0`. An alternative solution is to set `neighbor-list mode manual` and not +configure any `neighbor-list` entries. + +==== Local-BSS Neighbors + +Local neighbors can be configured by just the local BTS number, or by LAC+CI, +or any other supported A-interface type cell identification; also including the +ARFCN+BSIC is optional, it will be derived from the local configuration if +omitted. + +OsmoBSC will log errors in case the configuration includes ambiguous ARFCN+BSIC +relations (when one given cell has more than one neighbor for any one +ARFCN+BSIC). + +Neighbor relations must be configured explicitly in both directions, i.e. each +cell has to name all of its neighbors, even if the other cell already has an +identical neighbor relation in the reverse direction. + +.Example: configuring neighbors within the local BSS in osmo-bsc.cfg, identified by local BTS number +---- +network + bts 0 + neighbor bts 1 + bts 1 + neighbor bts 0 +---- + +.Example: configuring neighbors within the local BSS in osmo-bsc.cfg, identified by LAC+CI +---- +network + + bts 0 + # this cell's LAC=23 CI=5 + location_area_code 23 + cell_identity 5 + # reference bts 1 + neighbor lac-ci 23 6 + + bts 1 + # this cell's LAC=23 CI=6 + location_area_code 23 + cell_identity 6 + # reference bts 0 + neighbor lac-ci 23 5 +---- + +It is allowed to include the ARFCN and BSIC of local neighbor cells, even +though that is redundant with the already known local configuration of the +other cell. The idea is to ease generating the neighbor configuration +automatically, since local-BSS and remote-BSS neighbors then share identical +configuration formatting. For human readability and maintainability, it may +instead be desirable to use the `neighbor bts <0-255>` format. + +.Example: configuring neighbors within the local BSS in osmo-bsc.cfg, redundantly identified by LAC+CI as well as ARFCN+BSIC +---- +network + + bts 0 + # this cell's LAC=23 CI=5 + location_area_code 23 + cell_identity 5 + # this cell's ARFCN=1 BSIC=1 + trx 0 + arfcn 1 + base_station_id_code 1 + # reference bts 1 + neighbor lac-ci 23 6 arfcn 2 bsic 2 + + bts 1 + # LAC=23 CI=6 + location_area_code 23 + cell_identity 6 + # this cell's ARFCN=2 BSIC=2 + trx 0 + arfcn 2 + base_station_id_code 2 + # reference bts 0 + neighbor lac-ci 23 5 arfcn 1 bsic 1 +---- + +If the cell identification matches a local cell, OsmoBSC will report errors if +the provided ARFCN+BSIC do not match. + +==== Remote-BSS Neighbors + +Remote-BSS neighbors _always_ need to be configured with full A-interface +identification _and_ ARFCN+BSIC, to allow mapping a cell's neighbor ARFCN+BSIC +to a _BSSMAP Cell Identifier_ (see 3GPP TS 48.008 3.1.5.1 Handover Required +Indication and 3.2.1.9 HANDOVER REQUIRED). + +.Example: configuring remote-BSS neighbors in osmo-bsc.cfg, identified by LAC+CI (showing both BSCs' configurations) +---- +# BSC Alpha's osmo-bsc.cfg +network + bts 0 + # this cell's LAC=23 CI=6 + location_area_code 23 + cell_identity 6 + # this cell's ARFCN=2 BSIC=2 + trx 0 + arfcn 2 + base_station_id_code 2 + # fully describe the remote cell by LAC+CI and ARFCN+BSIC + neighbor lac-ci 42 3 arfcn 1 bsic 3 + +# BSC Beta's osmo-bsc.cfg +network + bts 0 + # this cell's LAC=42 CI=3 + location_area_code 42 + cell_identity 3 + # this cell's ARFCN=1 BSIC=3 + trx 0 + arfcn 1 + base_station_id_code 3 + # fully describe the remote cell by LAC+CI and ARFCN+BSIC + neighbor lac-ci 23 6 arfcn 2 bsic 2 +---- + +NOTE: It is strongly recommended to stick to a single format for remote-BSS +neighbors' cell identifiers all across an OsmoBSC configuration; i.e. decide +once to use `lac`, `lac-ci` or `cgi` and then stick to that within a given +osmo-bsc.cfg. The reason is that the _Cell Identifier List_ sent in the _BSSMAP +Handover Required_ message must have one single cell identifier type for all +list items. Hence, to be able to send several alternative remote neighbors to +the MSC, the configured cell identifiers must be of the same type. If in doubt, +use the full CGI identifier everywhere. + +==== Reconfiguring Neighbors in a Running OsmoBSC + +When modifying a cell's neighbor configuration in a telnet VTY session while a cell is already active, +the neighbor configuration will merely be cached in the BSC's local config. To take actual effect, it is +necessary to + +- either, re-connect the cell to the BSC (e.g. via `drop bts connection <0-255> oml`) +- or, re-send the System Information using `bts <0-255> resend-system-information`. + +=== Configuring Handover Decisions + +For a long time, OsmoBSC has supported handover based on reception level +hysteresis (RXLEV) and distance (TA, Timing Advance), known has `algorithm 1`. + +Since 2018, OsmoBSC also supports a load-based handover decision algorithm, +known as `algorithm 2`, which also takes cell load, available codecs and +oscillation into consideration. Algorithm 2 had actually been implemented for +the legacy OsmoNITB program many years before the OsmoMSC split, but remained +on a branch, until it was forward-ported to OsmoBSC in 2018. + +.What handover decision algorithms take into account +[frame="none",grid="none",cols="^10%,^10%,80%"] +|==== +| algorithm 1 | algorithm 2 | +| ✓ | ✓| RXLEV +| ✓ | ✓| RXQUAL +| ✓ | ✓| TA (distance) +| ✓ | ✓| interference (good RXLEV, bad RXQUAL) +| | ✓| load (nr of free lchans, minimum RXLEV and RXQUAL) +| | ✓| penalty time to avoid oscillation +| | ✓| voice rate / codec bias +| ✓ | | inter-BSC: RXLEV hysteresis +| | ✓| inter-BSC: only below minimum RXLEV, RXQUAL +|==== + +==== Common Configuration + +Handover is disabled by default; to disable/enable handover, use `handover +(0|1)`. + +Once enabled, algorithm 1 is used by default; choose a handover algorithm with +`handover algorithm (1|2)`: + +---- +network + # Enable handover + handover 1 + + # Choose algorithm + handover algorithm 2 + + # Tweak parameters for algorithm 2 (optional) + handover2 min-free-slots tch/f 4 + handover2 penalty-time failed-ho 30 + handover2 retries 1 +---- + +All handover algorithms share a common configuration scheme, with an overlay of +three levels: + +* immutable compile-time default values, +* configuration on the `network` level for all cells, +* individual cells' configuration on each `bts` node. + +Configuration settings relevant for algorithm 1 start with `handover1`, for +algorithm 2 with `handover2`. + +The following example overrides the compile-time default for all cells, and +furthermore sets one particular cell on its own individual setting, for the +`min-free-slots tch/f` value: + +---- +network + handover2 min-free-slots tch/f 4 + bts 23 + handover2 min-free-slots tch/f 2 +---- + +The order in which these settings are issued makes no difference for the +overlay; i.e., this configuration is perfectly identical to the above, and the +individual cell's value remains in force: + +---- +network + bts 23 + handover2 min-free-slots tch/f 2 + handover2 min-free-slots tch/f 4 +---- + +Each setting can be reset to a default value with the `default` keyword. When +resetting an individual cell's value, the globally configured value is used. +When resetting the global value, the compile-time default is used (unless +individual cells still have explicit values configured). For example, this +telnet VTY session removes above configuration first from the cell, then from +the global level: + +---- +OsmoBSC(config)# network +OsmoBSC(config-net)# bts 23 +OsmoBSC(config-net-bts)# handover2 min-free-slots tch/f default +% 'handover2 min-free-slots tch/f' setting removed, now is 4 +OsmoBSC(config-net-bts)# exit +OsmoBSC(config-net)# handover2 min-free-slots tch/f default +% 'handover2 min-free-slots tch/f' setting removed, now is 0 +---- + +==== Handover Algorithm 1 + +Algorithm 1 takes action only when RR Measurement Reports are received from a +BTS. As soon as a neighbor's average RXLEV is higher than the current cell's +average RXLEV plus a hysteresis distance, handover is triggered. + +If a handover fails, algorithm 1 will again attempt handover to the same cell +with the next Measurement Report received. + +Configuration settings relevant for algorithm 1 start with `handover1`. For +further details, please refer to the OsmoBSC VTY Reference +(<<vty-ref-osmobsc>>) or the telnet VTY online documentation. + +==== Handover Algorithm 2 + +Algorithm 2 is specifically designed to distribute load across cells. A +subscriber will not necessarily remain attached to the cell that has the best +RXLEV average, if that cell is heavily loaded and a less loaded neighbor is +above the minimum allowed RXLEV. + +Algorithm 2 also features penalty timers to avoid oscillation: for each +subscriber, if handover to a specific neighbor failed (for a configurable +number of retries), a holdoff timer prevents repeated attempts to handover to +that same neighbor. Several hold-off timeouts following specific situations are +configurable (see `handover2 penalty-time` configuration items). + +Configuration settings relevant for algorithm 2 start with `handover2`. For +further details, please refer to the OsmoBSC VTY Reference +<<vty-ref-osmobsc>> or the telnet VTY online documentation. + +===== Load Distribution + +Load distribution is only supported by algorithm 2. + +Load distribution occurs: + +- explicitly: every N seconds, OsmoBSC considers all local cells and actively + triggers handover operations to reduce congestion, if any. See + `min-free-slots` below, and the `congestion-check` setting. + +- implicitly: when choosing the best neighbor candidate for a handover + triggered otherwise, a congested cell (in terms of `min-free-slots`) is only + used as handover target if there is no alternative that causes less cell + load. + +In either case, load distribution will only occur towards neighbor cells that +adhere to minimum reception levels and distance, see `min rxlev` and `max +distance`. + +Load distribution will take effect only for already established voice channels. +An MS will always first establish a voice call with its current cell choice; in +load situations, it might be moved to another cell shortly after that. +Considering the best neighbor _before_ starting a new voice call might be +desirable, but is currently not implemented. Consider that RXLEV/RXQUAL ratings +are averaged over a given number of measurement reports, so that the neighbor +ratings may not be valid/reliable yet during early call establishment. In +consequence, it is recommended to ensure a sufficient number of unused logical +channels at all times, though there is no single correct configuration for all +situations. + +Most important for load distribution are the `min-free-slots tch/f` and +`min-free-slots tch/h` settings. The default is zero, meaning _no_ load +distribution. To enable, set `min-free-slots` >= 1 for `tch/f` and/or `tch/h` +as appropriate. This setting refers to the minimum number of voice channels +that should ideally remain unused in each individual BTS at all times. + +NOTE: it is not harmful to configure `min-free-slots` for a TCH kind that is +not actually present. Such settings will simply be ignored. + +NOTE: the number of TCH/F timeslots corresponds 1:1 to the number indicated by +`min-free-slots tch/f`, because each TCH/F physical channel has exactly one +logical channel. In contrast, for each TCH/H timeslot, there are two logical +channels, hence `min-free-slots tch/h` corresponds to twice the number of TCH/H +timeslots configured per cell. In fact, a more accurate naming would have been +"min-free-lchans". + +Think of the `min-free-slots` setting as the threshold at which load +distribution is considered. If as many logical channels as required by this +setting are available in a given cell, only changes in RXLEV/RXQUAL/TA trigger +handover away from that cell. As soon as less logical channels remain free, the +periodical congestion check attempts to distribute MS to less loaded neighbor +cells. Every time, the one MS that will suffer the least RXLEV loss while still +reducing congestion will be instructed to move first. + +If a cell and its neighbors are all loaded past their `min-free-slots` +settings, the algorithmic aim is equal load: a load-based handover will never +cause the target cell to be more congested than the source cell. + +The min-free-slots setting is a tradeoff between immediate voice service +availability and optimal reception levels. A sane choice could be: + +- Start off with `min-free-slots` set to half the available logical channels. +- Increase `min-free-slots` if you see MS being rejected too often even though + close neighbors had unused logical channels. +- Decrease `min-free-slots` if you see too many handovers happening for no + apparent reason. + +Choosing the optimal setting is not trivial, consider these examples: + +- Configure `min-free-slots` = 1: load distribution to other cells will occur + exactly when the last available logical channel has become occupied. The next + time the congestion check runs, at most one handover will occur, so that one + channel is available again. In the intermediate time, all channels will be + occupied, and some MS might be denied immediate voice service because of + that, even though, possibly, other neighbor cells would have provided + excellent reception levels and were completely unloaded. For those MS that + are already in an ongoing voice call and are not physically moving, though, + this almost guarantees service by the closest/best cell. + +- Set `min-free-slots` = 2: up to two MS can successfully request voice service + simultaneously (e.g. one MS is establishing a new voice call while another MS + is travelling into this cell). Ideally, two slots have been kept open and are + immediately available. But if a third MS is also traveling into this cell at + the same time, it will not be able to handover into this cell until load + distribution has again taken action to make logical channels available. The + same scenario applies to any arbitrary number of MS asking for voice channels + simultaneously. The operator needs to choose where to draw the line. + +- Set `min-free-slots` >= the number of available channels: as soon as any + neighbor is less loaded than a given cell, handover will be attempted. But + imagine there are only two active voice calls on this cell with plenty of + logical channels still unused, and the closest neighbor rates only just above + `min rxlev`; then moving one of the MS _for no good reason_ causes all of: + increased power consumption, reduced reception stability and channel + management overhead. + +NOTE: In the presence of dynamic timeslots to provide GPRS service, the number +of voice timeslots left unused also determines the amount of bandwidth +available for GPRS. + +==== External / Inter-BSC Handover Considerations + +There currently is a profound difference for inter-BSC handover between +algorithm 1 and 2: + +For algorithm 1, inter-BSC handover is triggered as soon as the Measurement +Reports and hysteresis indicate a better neighbor than the current cell, +period. + +For algorithm 2, a subscriber is "sticky" to the current BSS, and inter-BSC +handover is only even considered when RXLEV/TA drop below minimum requirements. + +- If your network topology is such that each OsmoBSC instance manages a single + BTS, and you would like to encourage handover between these, choose handover + algorithm 1. Load balancing will not be available, but RXLEV hysteresis will. + +- If your network topology has many cells per BSS, and/or if your BSS + boundaries in tendency correspond to physical/semantic boundaries that favor + handover to remain within a BSS, then choose handover algorithm 2. + +The reason for the difference between algorithm 1 and 2 for remote-BSS +handovers is, in summary, the young age of the inter-BSC handover feature in +OsmoBSC: + +- So far the mechanisms to communicate cell load to remote-BSS available in the + BSSMAP Handover messages are not implemented, so, a handover due to cell load + across BSS boundaries would be likely to cause handover oscillation between + the two BSS (continuous handover of the same MS back and forth between the + same two cells). +- Algorithm 1 has no `min rxlev` setting. +- Algorithm 1 does not actually use any information besides the Measurement + Reports, and hence can trivially treat all neighbor cells identically. diff --git a/doc/manuals/chapters/handover_inter_bsc.dot b/doc/manuals/chapters/handover_inter_bsc.dot new file mode 100644 index 000000000..0cc655401 --- /dev/null +++ b/doc/manuals/chapters/handover_inter_bsc.dot @@ -0,0 +1,35 @@ +digraph G { +rankdir=LR + +subgraph cluster_bss_a { + label="BSS Alpha" + BTS_a0 [rank=min,label="bts 0\nARFCN=1 BSIC=1\nLAC=23 CI=5"] + BTS_a1 [rank=min,label="bts 1\nARFCN=2 BSIC=2\nLAC=23 CI=6"] + BSC_a [label="BSC Alpha"]; + {BTS_a0,BTS_a1} -> BSC_a [arrowhead=none,label=Abis] +} + +subgraph cluster_bss_b { + label="BSS Beta" + BTS_b0 [rank=min,label="bts 0\nARFCN=1 BSIC=3\nLAC=42 CI=3"] + BTS_b1 [rank=min,label="bts 1\nARFCN=2 BSIC=4\nLAC=42 CI=1"] + BSC_b [label="BSC Beta"] + {BTS_b0,BTS_b1} -> BSC_b [arrowhead=none,label=Abis] +} + +MS -> BTS_a1 [label="(3) Measurement:\nARFCN=1 BSIC=3 RXLEV"] +BTS_a1 -> MS [label="(1) my neighbors:\nARFCN=1 BSIC=1\nARFCN=1 BSIC=3"] +BTS_b0 -> MS [label="(2) good RXLEV",style=dotted] +MS -> {BTS_a0,BTS_b0,BTS_b1} [style=invisible,arrowhead=none] + +BTS_a1 -> BSC_a [label="(4) Measurement\nReport",style=dashed] +BTS_a1 -> BTS_b0 [label="(5) BSC decides to do\ninter-BSC Handover",style=dashed,constraint=false] + +{BSC_a,BSC_b} -> MSC [arrowhead=none,label=A] + +BSC_a -> MSC [label="(6) --> Handover Required\nto LAC=42 CI=6\n(10) <-- Handover Command",style=dashed,constraint=false,arrowhead=none] +MSC -> BSC_b [label="(7) <-- Handover Request\n(9) --> Handover Request ACK",style=dashed,constraint=false,arrowhead=none] + +BSC_b -> BTS_b0 [label="(8) activate new lchan",style=dashed,constraint=false] + +} diff --git a/doc/manuals/chapters/handover_intra_bsc.dot b/doc/manuals/chapters/handover_intra_bsc.dot new file mode 100644 index 000000000..2a4f6cf15 --- /dev/null +++ b/doc/manuals/chapters/handover_intra_bsc.dot @@ -0,0 +1,31 @@ +digraph G { +rankdir=LR + +subgraph cluster_bss_a { + label="BSS Alpha" + BTS_a0 [rank=min,label="bts 0\nARFCN=1 BSIC=1\nLAC=23 CI=5"] + BTS_a1 [rank=min,label="bts 1\nARFCN=2 BSIC=2\nLAC=23 CI=6"] + BSC_a [label="BSC Alpha"]; + {BTS_a0,BTS_a1} -> BSC_a [arrowhead=none,label=Abis] +} + +subgraph cluster_bss_b { + label="BSS Beta" + BTS_b0 [rank=min,label="bts 0\nARFCN=1 BSIC=3\nLAC=42 CI=3"] + BTS_b1 [rank=min,label="bts 1\nARFCN=2 BSIC=4\nLAC=42 CI=1"] + BSC_b [label="BSC Beta"] + {BTS_b0,BTS_b1} -> BSC_b [arrowhead=none,label=Abis] +} + +MS -> BTS_a1 [label="(3) Measurement:\nARFCN=1 BSIC=1 RXLEV"] +BTS_a1 -> MS [label="(1) my neighbors:\nARFCN=1 BSIC=1\nARFCN=1 BSIC=3"] +BTS_a0 -> MS [label="(2) good RXLEV",style=dotted] +MS -> {BTS_a0,BTS_b0,BTS_b1} [style=invisible,arrowhead=none] + +BTS_a1 -> BSC_a [label="(4) Measurement\nReport",style=dashed] +BTS_a1 -> BTS_a0 [label="(5) BSC decides to do\nintra-BSC Handover",style=dashed,constraint=false] +BSC_a -> BTS_a0 [label="(6) activate new lchan",style=dashed,constraint=false] + +{BSC_a,BSC_b} -> MSC [arrowhead=none,label=A] + +} diff --git a/doc/manuals/chapters/overview.adoc b/doc/manuals/chapters/overview.adoc new file mode 100644 index 000000000..9b619fb24 --- /dev/null +++ b/doc/manuals/chapters/overview.adoc @@ -0,0 +1,174 @@ +[[overview]] +== Overview + +This manual should help you getting started with OsmoBSC. It will cover +aspects of configuring and running the OsmoBSC. + +[[intro_overview]] +=== About OsmoBSC + +OsmoBSC is the Osmocom implementation of a Base Station Controller. It +implements: + +- an 'A-bis' interface towards BTSs and +- an 'A' interface towards an MSC. It is important to be aware that there are + two variants of the 'A' interface, see <<a-interface>>. + +=== Software Components + +OsmoBSC contains a variety of different software components, which +we'll briefly describe in this section. + +==== A-bis Implementation + +OsmoBSC implements the ETSI/3GPP specified A-bis interface, including TS 08.56 +(LAPD), TS 08.58 (RSL) and TS 12.21 (OML). In addition, it supports a variety +of vendor-specific extensions and dialects in order to communicate with BTSs +from Siemens, Nokia, Ericsson, ip.access, Octasic and sysmocom, as well as +various USRP based BTS implementations, using OsmoBTS and OsmoTRX (like the +Ettus B200 series, the Fairwaves XTRX or the LimeSDR, to name a few). + +For more information, see <<bts>> and <<bts-examples>>. + +[[a-interface]] +==== A Implementation + +OsmoBSC implements a sub-set of the GSM A interface as specified in TS 08.08 +(BSSAP) and TS 04.08 (DTAP). + +Osmocom offers two variants of the 'A' interface's protocol stacking: + +- 'A/SCCPlite' +- 'A/SCCP/M3UA' + +Traditionally, OsmoBSC only implemented the A/SCCPlite protocol, but since a +proper M3UA implementation is available from 'libosmo-sigtran' +('libosmo-sccp.git'), the stock OsmoBSC now supports only A/SCCP/M3UA. (The +idea is that SCCPlite support may be added to libosmo-sigtran at some point +in the future, after which the new `osmo-bsc` would support both variants of +the A interface.) + +The difference between an A/SCCPlite and A/SCCP/M3UA is illustrated in +<<fig-sccplite>> and <<fig-sccp-m3ua>>. + +===== A/SCCPlite + +Unlike classic A interface implementations for E1 interfacs, +`osmo-bsc-sccplite` implements a variant of encapsulating the A interface over +IP. To do so, the SCCP messages are wrapped in an IPA multiplex and then +communicated over TCP. The audio channels are mapped to RTP streams. + +This protocol stacking is sometimes called "SCCPlite". + +At the time of writing, if you would like to use the old A/SCCPlite protocol, +look for binary packages named `osmo-bsc-sccplite`, or compile `osmo-bsc` from +the 'openbsc.git' repository. + +[[fig-sccplite]] +.`osmo-bsc-sccplite` operation using 'A/SCCPlite' +[graphviz] +---- +digraph G { + rankdir=LR; + MS0 [label="MS"]; + MS1 [label="MS"]; + MS2 [label="MS"]; + MS3 [label="MS"]; + BTS0 [label="BTS"]; + BTS1 [label="BTS"]; + BSC [label="OsmoBSC-SCCPlite"]; + MSC [label="3rd party MSC"]; + {MS0,MS1}->BTS0 [label="Um"]; + {MS2,MS3}->BTS1 [label="Um"]; + {BTS0,BTS1}->BSC [label="Abis\nTCP\nIP"]; + BSC->MSC [label="A\nSCCP\nTCP\nIP"]; +} +---- + +===== A/SCCP/M3UA + +The default OsmoBSC's A interface uses the M3UA variant of SIGTRAN protocol +stacking: + +|===== +|A +|SCCP +|M3UA +|SCTP +|IP +|===== + +To use the now-default A/SCCP/M3UA protocol, look for binary packages named +`osmo-bsc`, or compile `osmo-bsc` from the 'osmo-bsc.git' repository. It is +recommended to use the M3UA variant, which is required to operate with OsmoMSC. + +To route SCCP/M3UA messages between OsmoBSC and and MSC, an STP instance like +OsmoSTP is required. + +[[fig-sccp-m3ua]] +.`osmo-bsc` operation using 'A/SCCP/M3UA' +[graphviz] +---- +digraph G { + rankdir=LR; + MS0 [label="MS"]; + MS1 [label="MS"]; + MS2 [label="MS"]; + MS3 [label="MS"]; + BTS0 [label="BTS"]; + BTS1 [label="BTS"]; + BSC [label="OsmoBSC"]; + STP [label="OsmoSTP"]; + MSC [label="OsmoMSC\n(or 3rd-party MSC)"]; + {MS0,MS1}->BTS0 [label="Um"]; + {MS2,MS3}->BTS1 [label="Um"]; + {BTS0,BTS1}->BSC [label="Abis\nTCP\nIP"]; + BSC->STP->MSC [label="A\nSCCP\nM3UA\nSCTP\nIP"]; +} +---- + +==== BSC Implementation + +The BSC implementation covers the classic functionality of a GSM Base +Station Controller, i.e. + +* configuring and bringing up BTSs with their TRXs and TSs +* implementing the A-bis interface / protocols for signalling and actual + voice data (TRAU frames). +* processing measurement results from the mobile stations in dedicated + mode, performing hand-over decision and execution. +* Terminating the TS 04.08 RR (Radio Resource) sub-layer from the MS. + +For more information, see <<net>>, <<bts>> and <<bts-examples>>. + + +==== TRAU mapper / E1 sub-channel muxer + +Unlike classic GSM networks, OsmoBSC does not perform any transcoding. +Rather, a compatible codec is selected for both legs of a call, and +codec frames are passed through transparently. In order to achieve this +with E1 based BTS, OsmoBSC contains a E1 sub-channel de- and +re-multiplexer as well as a TRAU mapper that can map uplink to downlink +frames and vice versa. + +=== Control interface + +The actual protocol is described in <<common-control-if>> section. Here we +describe variables specific to OsmoBSC. + +.Variables available over control interface +[options="header",width="100%",cols="20%,5%,5%,50%,20%"] +|=== +|Name|Access|Trap|Value|Comment +|msc_connection_status|RO|Yes|"connected", "disconnected"|Indicate the status of connection to MSC. +|bts_connection_status|RO|Yes|"connected", "disconnected"|Indicate the status of connection to BTS. +|location|RW|Yes|"<unixtime>,(invalid\|fix2d\|fix3d),<lat>,<lon>,<height>"|Set/Get location data. +|timezone|RW|No|"<hours>,<mins>,<dst>", "off"|-19 <= hours <= 19, mins in {0, 15, 30, 45}, and 0 <= dst <= 2 +|notification|WO|Yes|| +|inform-msc-v1|WO|Yes|| +|ussd-notify-v1|WO|Yes|| +|=== + +Some comments. +FIXME: commands defined in src/ctrl/control_if.c? Nodes? Traps? + diff --git a/doc/manuals/chapters/running.adoc b/doc/manuals/chapters/running.adoc new file mode 100644 index 000000000..f62ba6e8b --- /dev/null +++ b/doc/manuals/chapters/running.adoc @@ -0,0 +1,42 @@ +== Running OsmoBSC + +The OsmoBSC executable (`osmo-bsc`) offers the following command-line +arguments: + +=== SYNOPSIS + +*osmo-bsc* [-h|-V] [-d 'DBGMASK'] [-D] [-c 'CONFIGFILE'] [-s] [-T] [-e 'LOGLEVEL'] [-l 'IP'] [-r 'RFCTL'] + +=== OPTIONS + +*-h, --help*:: + Print a short help message about the supported options +*-V, --version*:: + Print the compile-time version number of the OsmoBTS program +*-d, --debug 'DBGMASK','DBGLEVELS'*:: + Set the log subsystems and levels for logging to stderr. This + has mostly been superseded by VTY-based logging configuration, + see <<logging>> for further information. +*-D, --daemonize*:: + Fork the process as a daemon into background. +*-c, --config-file 'CONFIGFILE'*:: + Specify the file and path name of the configuration file to be + used. If none is specified, use `osmo-bsc.cfg` in the current + working directory. +*-s, --disable-color*:: + Disable colors for logging to stderr. This has mostly been + deprecated by VTY based logging configuration, see <<logging>> + for more information. +*-T, --timestamp*:: + Enable time-stamping of log messages to stderr. This has mostly + been deprecated by VTY based logging configu- ration, see + <<logging>> for more information. +*-e, --log-level 'LOGLEVEL'*:: + Set the global log level for logging to stderr. This has mostly + been deprecated by VTY based logging configuration, see + <<logging>> for more information. +*-l, --local='IP'*:: + Specify the local IP address of the OsmoBSC-MGCP +*-r, --rf-ctl 'RFCTL'*:: + Offer a Unix domain socket for RF control at the path/filename + 'RFCTL' in the file system. |