== Configuring OsmoPCU Contrary to other network elements (like OsmoBSC, OsmoNITB), the OsmoPCU has a relatively simple minimum configuration. This is primarily because most of the PCU configuration happens indirectly from the BSC, who passes the configuation over A-bis OML via OsmoBTS and its PCU socket into OsmoPCU. A minimal OsmoPCU configuration file is provided below for your reference: .Example: Minimal OsmoPCU configuration file (`osmo-pcu.cfg`) ---- pcu flow-control-interval 10 <1> cs 2 <2> alloc-algorithm dynamic <3> gamma 0 ---- <1> send a BSSGP flow-control PDU every 10 seconds <2> start a TBF with the initial coding scheme 2 <3> dynamically chose between single-slot or multi-slot TBF allocations depending on system load However, there are plenty of tuning parameters for people interested to optimize PCU throughput or latency according to their requirements. === Configuring the Coding Schemes and Rate Adaption As a reminder: - GPRS supports Coding Schemes 1-4 (CS1-4), all of them use GMSK modulation (same as GSM). - EGPRS supports MCS1-9, where MCS1-4 is GMSK, and MCS5-9 use 8-PSK modulation. The range of Coding Schemes above only apply to RLCMAC data blocks; RLCMAC control blocks are always transmitted with CS1 (GMSK). Hence, CS1 is always supported and must be always permitted. The BSC includes a bit-mask of permitted [E]GPRS coding schemes as part of the A-bis OML configuration, controlled by VTY `gprs mode (none|gprs|egprs)`. This is passed from the BTS via the PCU socket into OsmoPCU, and the resulting set can be further constrained by OsmoPCU VTY configuration. Some additional OsmoPCU parameters can be set as described below. ==== Initial Coding Scheme You can use the `cs <1-4> [<1-4>]` command at the `pcu` VTY config node to set the initial GPRS coding scheme to be used. The optional second value allows to specify a different initial coding scheme for uplink. Similarly, `mcs <1-9> [<1-9>]` can be used to set up the initial EGPRS coding scheme. [[max_cs_mcs]] ==== Maximum Coding Scheme You can use the `cs max <1-4> [<1-4>]` command at the `pcu` VTY config node to set the maximum GPRS coding scheme that should be used as part of the rate adaption. The optional second value allows to specify a different maximum coding scheme for uplink. Similarly, `mcs max <1-9> [<1-9>]` can be used to set up the maximum EGPRS coding scheme. The actual Maximum Coding Scheme for each direction used at runtime is actually the result of taking the maximum value from the permitted GPRS coding schemes received by the BSC (or BTS) over PCUIF which is equal or lower tho the configured value. Example: PCUIF announces permitted MCS bit-mask (`MCS1 MCS2 MCS3 MCS4`) and OsmoPCU is configured `mcs max 6`, then the actual maximum MCS used at runtime will be `MCS4`. ==== Rate Adaption Error Thresholds You can use the `cs threshold <0-100> <0-100>` command at the `pcu` VTY config node to determine the upper and lower limit for the error rate percentage to use in the rate adaption. If the upper threshold is reached, a lower coding sheme is chosen, and if the lower threshold is reached, a higher coding scheme is chosen. ==== Rate Adation Link Quality Thresholds You can use the `cs link-quality-ranges cs1 <0-35> cs2 <0-35> <0-35> cs3 <0-35> <0-35> cs4 <0-35>` command at the `pcu` VTY config node to tune the link quality ranges for the respective coding schemes. ==== Data Size based CS downgrade Threshold You can use the `cs downgrade-threshold <1-10000>` command at the `pcu` VTY config node to ask the PCU to down-grade the coding scheme if less than the specified number of octets are left to be transmitted. === Miscellaneous Configuration / Tuning Parameters ==== Downlink TBF idle time After a down-link TBF is idle (all data in the current LLC downlink queue for the MS has been transmitted), we can keep the TBF established for a configurable time. This avoids having to go through a new one or two phase TBF establishment once the next data for downlink arrives. You can use the `dl-tbf-idle-time <1-5000>` to specify that time in units of milli-seconds. The default is 2 seconds. ==== MS idle time Using the `ms-idle-time <1-7200>` command at the `pcu` VTY config node you can configure the number of seconds for which the PCU should keep the MS data structure alive before releasing it if there are no active TBF for this MS. The OsmoPCU default value is 60 seconds, which is slightly more than what 3GPP TS 24.008 recommends for T3314 (44s). The MS data structure only consumes memory in the PCU and does not require any resources of the air interface. ==== Forcing two-phase access If the MS is using a single-phase access, you can still force it to use a two-phase access using the `two-phase-access` VTY configuration command at the `pcu` VTY config node. === Configuring BSSGP flow control BSSGP between SGSN and PCU contains a two-level nested flow control mechanism: . one global flow control instance for the overall (downlink) traffic from the SGSN to this PCU . a per-MS flow control instance for each individual MS served by this PCU Each of the flow control instance is implemented as a TBF (token bucket filter). ==== Normal BSSGP Flow Control Tuning parameters You can use the following commands at the `pcu` VTY config node to tune the BSSGP flow control parameters: `flow-control-interval <1-10>`:: configure the interval (in seconds) between subsequent flow control PDUs from PCU to SGSN `flow-control bucket-time <1-65534>`:: set the target downlink maximum queueing time in centi-seconds. The PCU will attempt to adjust the advertised bucket size to match this target. ==== Extended BSSGP Flow Control Tuning parameters There are some extended flow control related parameters at the `pcu` VTY config node that override the automatic flow control as specified in the BSSGP specification. Use them with care! `flow-control force-bvc-bucket-size <1-6553500>`:: force the BVC (global) bucket size to the given number of octets `flow-control force-bvc-leak-rate <1-6553500>`:: force the BVC (global) bucket leak rate to the given number of bits/s `flow-control force-ms-bucket-size <1-6553500>`:: force the per-MS bucket size to the given number of octets `flow-control force-ms-leak-rate <1-6553500>`:: force the per-MS bucket leak rate to the given number of bits/s === Configuring LLC queue The downlink LLC queue in the PCU towards the MS can be tuned with a variety of parameters at the `pcu` VTY config node, depending on your needs. `queue lifetime <1-65534>`:: Each downlink LLC PDU is assigned a lifetime by the SGSN, which is respected by the PDU *unless* you use this command to override the PDU lifetime with a larger value (in centi-seconds) `queue lifetime infinite`:: Never drop LLC PDUs, i.e. give them an unlimited lifetime. `queue hysteresis <1-65535>`:: When the downlink LLC queue is full, the PCU starts dropping packets. Using this parameter, we can set the lifetime hysteresis in centi-seconds, i.e. it will continue discarding until "lifetime - hysteresis" is reached. `queue codel`:: Use the 'CoDel' (Controlled Delay) scheduling algorithm, which is designed to overcome buffer bloat. It will use a default interval of 4 seconds. `queue codel interval <1-1000>`:: Use the 'CoDel' (Controlled Delay) scheduling algorithm, which is designed to overcome buffer bloat. Use the specified interval in centi-seconds. `queue idle-ack-delay <1-65535>`:: Delay the request for an ACK after the last downlink LLC frame by the specified amount of centi-seconds. === Configuring MS power control GPRS MS power control works completely different than the close MS power control loop in circuit-switched GSM. Rather than instructing the MS constantly about which transmit power to use, some parameters are provided to the MS by which the MS-based power control algorithm is tuned. See 3GPP TS 05.08 for further information on the algorithm and the parameters. You can set those parameters at the `pcu` VTY config node as follows: `gamma <0-62>`:: Set the gamma parameter for MS power control in units of dB. Parameter `ALPHA` is set on the BSC VTY configuration file on a per-BTS basis, and forwarded by OsmoPCU to the MS through the SI13 received from the former over PCUIF. OsmoPCU VTY command `alpha <0-10>` overrides the value received over PCUIF to keep backward compatibility with existing config files, but it is currently deprecated and its use is discouraged; one should configure it per-BTS in OsmoBSC VTY instead. === Configuring Network Assisted Cell Change (NACC) Network Assisted Cell Change, defined in 3GPP TS 44.060 sub-clause 8.8, is a feature providing the MS aid when changing to a new cell due to autonomous reselection. In summary, the MS informs the current cell its intention to change to a new target cell, and the network decides whether to grant the intended cell change or order a change to another neighbor cell. It also provides several System Informations of the target cell to the MS to allow for quicker reselection towards it. OsmoPCU will automatically provide the required neighbor System Information when the MS requests NACC towards a target cell also under the management of the same OsmoPCU instance, since it already has the System Information of all BTS under their control, obtained through PCUIF when the BTS registers against OsmoPCU, so no specific user configuration is required here. In general, OsmoPCU requires to gather the information from somewhere else before being able to provide it to the MS requesting the NACC. If OsmoPCU fails to gather the System Information, it will simply answer the MS allowing the proposed changed but without previously providing the System Information of the target cell. ==== Neighbor Address Resolution First of all, it needs to translate the identity of the target cell to change to, provided by the MS, into an identity that the Core Network can use and understand to identify the target cell, which happens to be a key composed of . This key is also named conveniently as CGI-PS, since it actually equals to the Circuit Switch CGI + RAC. In order to apply this target cell identity translation, OsmoPCU uses the OsmoBSC Neighbor Resolution Service. This service is nowadays provided by means of PCUIF container messages, which are transparently forwarded in both directions by the BTS using the IPA multiplex of the OML connection against the BSC. No specific configuration is required in any of the involved nodes, they should behave properly out of the box. These neighbor address resolutions ( => ) are by default cached for a while, in order to avoid querying the BSC frequently. As a result, the resolution time is also optimized. .Example: Configure Neighbor Resolution cache and timeouts ---- pcu timer X1 500 <1> timer X0 60 <2> ---- <1> Time out if the BSC doesn't answer our resolution request after 500 ms <2> Keep resolved neighbor addresses cached for 60 seconds ===== OsmoBSC CTRL interface (deprecated) CAUTION: This interface is nowadays considered deprecated and should not be used anymore. Any related VTY options should be dropped from configuration files, to let OsmoPCU use the new interface instead. This section is kept here for a while as a reference for old deployments using old versions of the programs. This Neighbor Address Resolution Service was initially implemented by means of a separate CTRL interface (see OsmoBSC User Manual), where OsmoPCU would create a CTRL connection to the BSC each time an address resolution was required. Older versions of OsmoBSC may not support the current Neighbor Address Resolution Service over the IPA multiplex (see above). For those cases, OsmoPCU can be configured to use the old deprecated CTRL interface. By default, the use of this interface is not configured and hence disabled in OsmoPCU. As a result, until configured, the network won't be able to provide the System Information to the MS prior to allowing the change during NACC against remote cells, which means the cell change will take longer to complete. In order to configure the interface, the OsmoBSC IP address and port to connect to must be configured in OsmoPCU VTY. .Example: Configure Neighbor Resolution CTRL interface against OsmoBSC ---- pcu neighbor resolution 172.18.13.10 4248 <1> ---- <1> Port 4248 is the default and hence could be omitted in this case ==== System Information Resolution Once OsmoPCU gains knowledge of the target cell's address in the Core Network, it can query its System Information. OsmoPCU will gather the requested System Information of target cells under its control without need for any external query, since the System Information of all BTSs it manages are received over PCUIF and stored internally in OsmoPCU. For those targets cells not managed by the OsmoPCU instance, the query is accomplished by using RIM procedures (NACC RAN-INFO application) over the Gb interface against the SGSN that OsmoPCU is connected to. In its turn, the SGSN will potentially forward this query to the PCU serving the target cell, which will provide back the System Information of that cell. The System Information received from external PCUs over RIM are by default cached for a while in order to avoid querying the SGSN frequently and, as a result, optimizing the resolution time too. .Example: Configure System Information resolution ---- pcu timer X2 500 <1> timer X11 60 <2> ---- <1> Time out if the SGSN doesn't answer our RIM RAN-INFO request request after 500 ms <2> Keep resolved remote neighbor System Information cached for 60 seconds [[cfg_e1_line]] === Configuring E1 line for CCU access Depending on the configuration the PCU may require direct access to a BTS CCU (channel coding unit) via an E1 line. This is in particular the case when OsmoPCU runs in co-location with OsmoBSC. The exact timeslot configuration is passed to the PCU via the pcu_sock interface. Only basic E1 line settings are required. However, it is important that the E1 line number is the same as the E1 line number that is used in the timeslot configuration of OsmoBSC. .Example: Configure an E1 line ---- e1_input e1_line 0 driver dahdi e1_line 0 port 2 no e1_line 0 keepalive ---- === GPRS vs EGPRS considerations ==== Configuration OsmoPCU can be configured to either: - Allocate only GPRS TBFs to all MS (no EGPRS) - Allocate EGPRS TBFs to EGPRS capable phones while still falling back to allocating GPRS TBFs on GPRS-only capable MS. These two different modes of operation are selected by properly configuring the Coding Schemes (see <>). The first mode of operation (GPRS-only for all MS) can be accomplished configuring OsmoPCU so that the resulting MCS set is empty. This can be done in two ways: - Announcing an empty MCS bit-mask over PCUIF to OsmoPCU: That's actually done automatically by OsmoBSC on BTS with VTY config set to `gprs mode gprs`. - Configuring OsmoPCU to force an empty set by using VTY command `mcs max 0`. Hence, if the resulting MCS bit-mask is not empty, (BSC configuring the BTS with `gprs mode egprs` and OsmoPCU VTY containing something other than 'mcs max 0'), EGPRS TBFs will be allocated for all MS announcing EGPRS capabilities. It is important to remark that in order to use MCS5-9, the BTS must support 8-PSK modulation. Nevertheless, in case 8-PSK is not supported by the BTS, one can still enable EGPRS and simply make sure 8-PSK MCS are never used by configuring OsmoPCU with `mcs max 4 4`. Similarly, a BTS may support 8-PSK modulation only on downlink, since it is easier to implement than the uplink, together with the fact that higher downlink throughput is usually more interesting from user point of view. In this scenario, OsmoPCU can be configured to allow for full MCS range in downlink while still preventing use of 8-PSK on the uplink: `mcs max 9 4`. Some other interesting configurations to control use of EGPRS in the network which lay outside OsmoPCU include: - If `osmo-bts-trx` together with `osmo-trx` is used, remember to enable EGPRS support (OsmoTRX VTY `egprs enable`). - It is possible to improve EGPRS performance (in particular, the TBF establishment timing) a bit by enabling 11-bit Access Burst support. This allows EGPRS capable phones to indicate their EGPRS capability, establishment cause, and multi-slot class directly in the Access Burst (OsmoTRX VTY `ext-rach enable`, OsmoBSC VTY `gprs egprs-packet-channel-request`). NOTE: If you enable MCS5-9 you will also need an 8-PSK capable OsmoBTS+PHY, which means `osmo-bts-sysmo` or `osmo-bts-litecell15` with their associated PHY, or `osmo-bts-trx` with `osmo-trx` properly configured. ==== GPRS+EGPRS multiplexing Both EGPRS and GPRS-only capable MS can be driven concurrently in the same PDCH timeslot by the PCU, hence no special configuration is required per timeslot regarding this topic; OsmoPCU scheduler takes care of the specific requirements when driving MS with different capabilities. These specific requirements translate to some restrictions regarding which Coding Schemes can be used at given frame numbers, and hence which kind of RLCMAC blocks can be sent, which means serving a GPRS-only MS in a PDCH may end up affecting slightly the downlink throughput of EGPRS capable MS. Throughput loss based on MS capabilities with TBF attached to a certain PDCH timeslot: All UEs are EGPRS capable:: No throughput loss, since all data is sent using EGPRS, and EGPRS control messages are used when appropriate. All UEs are GPRS-only (doesn't support EGPRS):: No throughput loss, since all data and control blocks use GPRS. Some UEs are GPRS-only, some EGPRS:: In general EGPRS capable UEs will use EGPRS, and GPRS-only UEs will use GPRS, with some restrictions affecting throughput of EGPRS capable UEs: - Whenever a GPRS-only MS is to be polled to send uplink data to PCU, then a downlink RLCMAC block modulated using GMSK must be sent, which means that if the scheduler selects a EGPRS MS for downlink on that block it will force sending of data with MCS1-4 (if it's new data, if it's a retransmission it cannot be selected since MCS from original message cannot be changed). In the worst case if no control block needs to be sent or no new data in MCS1-4 is available to send, then an RLCMAC Dummy Block is sent. - For synchronization purposes, each MS needs to receive an RLCMAC block which it can fully decode at least every 360ms, which means the scheduler must enforce a downlink block in CS1-4 every 360ms, that is, every 18th RLCMAC block. In general this is not a big issue since anyway all control RLCMAC blocks are encoded in CS1, so in case any control block is sent from time to time it's accomplished and there's no penalty. However, if only EGPRS downlink data is sent over that time frame, then the scheduler will force sending a RLCMAC Dummy Block. [[gsmtap]] === Configuring GSMTAP tracing In addition to being able to obtain pcap protocol traces of the NS/BSSGP communication and the text-based logging from the OsmoPCU software, there is also the capability of tracing all communication on the radio interface related to PS. To do so, OsmoPCU can encapsulate MAC blocks (23-155 byte messages at the L2-L1 interface depending on coding scheme) 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 specify the remote address of _GSMTAP_ host in the configuration file. In most cases, using 127.0.0.1 for passing the messages over the loopback (`lo`) device will be sufficient: .Example: Enabling GSMTAP Um-frame logging to localhost ---- pcu gsmtap-remote-host 127.0.0.1 <1> ---- <1> Destination address for _GSMTAP_ Um-frames NOTE: Changing this parameter at run-time will not affect the existing _GSMTAP_ connection, full program restart is required. NOTE: Command line parameters `-i` and `--gsmtap-ip` have been deprecated. OsmoPCU can selectively trace such messages based on different categories, for both Ul and Dl. For a complete list of cateogry values, please refer to the _OsmoPCU VTY reference manual_ <>. For example, to enable GSMTAP tracing for all DL EGPRS rlcmac data blocks, you can use the `gsmtap-category dl-data-egprs` command at the `pcu` node of the OsmoPCU VTY. .Example: Enabling GSMTAP for for all DL EGPRS rlcmac data blocks ---- OsmoPCU> enable OsmoPCU# configure terminal OsmoPCU(config)# pcu OsmoPCU(pcu)# gsmtap-category dl-data-egprs OsmoPCU(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 OsmoPCU. De-activation can be performed similarly by using the `no gsmtap-category dl-data-egprs` command at the `pcu` node of the OsmoPCU VTY. It may be useful to enable all categories with a few exceptions, or vice versa disable everything using one command. For this purpose, the VTY provides `gsmtap-category enable-all` and `gsmtap-category disable-all` commands. .Example: Enabling all categoriess except _dl-dummy_ ---- pcu gsmtap-category enable-all <1> no gsmtap-category dl-dummy <2> ---- <1> Enable all available SAPIs <2> Exclude DL RLCMAC blocks 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) of the specified remote address.