GSM/LTE LabKit AppNote: Legba LTE/GSM LabKit easy configuration for IoT tests

From YateBTS
Jump to: navigation, search

The GSM/LTE LabKit is very easily configurable for a wide range of purposes, including the most uncommon setups necessary for debugging and running virtually any IoT application. Advertising of all kind of configurations from the LabKit to UEs is achieved with plain XML files which are transformed into binary SIBs (System Information Blocks).

LabKit SIB configuration for IoT tests with XML files

XML files may include any information elements defined in the Release 12 3GPP specification (3GPP 36.331). Granular control of the LTE LabKit is useful for a variety of purposes, such as debugging a prototype IoT UE. By using Wireshark, Yate/YateBTS customers are able to get the transport blocks above the physical layer of communication between the UE and the eNB. The XML files can easily be edited via SSH and/or locally, due to the stand-alone computer architecture of the LTE LabKit.

Overview

System Information Blocks (SIBs) are broadcast messages that advertise the configuration of the eNodeB.

The yateenb module generates the binary content of its SIBs from XML files. The module parses these files whenever it is started or restarted. Any information elements defined in the Release 12 RRC specification (3GPP 36.331) can be encoded into these files, regardless of whether the associated features are actually supported in the yateenb module.

The XER-UPER encoder for these files is generated directly from the ASN.1 source code in the specifications. The syntax of the XML files is standard ASN.1 XER, except that the "-" character is substituted with "_" in element names and enumerated values.

For SIB Type 1, there are two possible XML files, one for TDD and one for FDD:

  • enb-sib1.fdd.xml
  • enb-sib1-tdd.xml

For all other SIB types there is a single possible XML file named "enb-SIB<N>.xml", where <N> is the SIB type.

In a Lab Kit or SatSite system, these files are located in /usr/share/yate/scripts.

Note: Advertising features that the eNodeB does not support may cause UE connections to fail. Understand the implications of any changes to the SIB content before making those changes. Save copies of the default, original SIB XML files before changing them.

Variable Substitution

The XML encoder can set the values of SIB information elements from "general" section of the yateenb.conf or yateenb-custom.conf configuration file. These values are substituted into the XML as strings before the XML-to-PER encoding step.

For example, here is the standard FDD SIB Type 1 XML file distributed with yateenb:

<systemInformationBlockType1>
  <cellAccessRelatedInfo>
    <plmn_IdentityList>
      <PLMN_IdentityInfo>
        <plmn_Identity>
          <mcc>${MCC}</mcc>
          <mnc>${MNC}</mnc>
        </plmn_Identity>
        <cellReservedForOperatorUse>notReserved</cellReservedForOperatorUse>
      </PLMN_IdentityInfo>
    </plmn_IdentityList>
    <trackingAreaCode>${TAC}</trackingAreaCode>
    <cellIdentity>${CellIdentity}</cellIdentity>
    <cellBarred>notBarred</cellBarred>
    <intraFreqReselection>allowed</intraFreqReselection>
    <csg_Indication>false</csg_Indication>
  </cellAccessRelatedInfo>
  <cellSelectionInfo>
    <q_RxLevMin>${RxLevMin}</q_RxLevMin>
  </cellSelectionInfo>
  <freqBandIndicator>${Band}</freqBandIndicator>
  <schedulingInfoList>
    <SchedulingInfo>
      <si_Periodicity>rf${SiPeriodicity}</si_Periodicity>
      <sib_MappingInfo>
          <SIB_Type>sibType3</SIB_Type>
          <SIB_Type>sibType4</SIB_Type>
      </sib_MappingInfo>
    </SchedulingInfo>
  </schedulingInfoList>
  <si_WindowLength>ms${SiWindowLength}</si_WindowLength>
  <systemInfoValueTag>0</systemInfoValueTag>
</systemInformationBlockType1>

In this example, the following elements take their values from the yateenb module configuration:

element
name
configuration
parameter
mcc MCC
mnc MNC
trackingAreaCode TAC
cellIdentity CellIdentity
q_RxLevMin RxLevMin
freqBandIndicator Band
si_Periodicity "rf" + SiPeriodicity
si_WindowLength "ms" + SiWindowLength

These particular configuration parameters are defined in yateenb.conf by the MMI or LMI, or they are defined with default values in the yateenb module itself during initialization.

You can also add new parameters to yateenb-custom.conf and then use them in the SIB XML files in this way. The only restrictions are:

  • The parameter name does not conflict with any existing yateenb parameter.
  • The new element or element value does not conflict with the actual implementation of the eNodeB.

So, for example, to make cell-barring configurable, change the line

<cellBarred>notBarred</cellBarred>

to something like

<cellBarred>${cellBarredParam}</cellBarred>

and then add some lines like this to yateenb-custom.conf:

; Cell Barred configuration in SIB1.
; Valid values are "notBarred" and "barred".
callBarredParam notBarred

Note: If you try to add new parameters to yatenb.conf instead of yateenb-custom.conf, the LMI or MMI will erase them the next time it updates the configuration.

Note: Parameters that are hard-coded in the SIBs provide reasonable default values in most cases. Changing them may degrade performance.

Error Checking

The yateenb module logs XML/SIB encoding errors the CRIT level. If you edit the XML files, be sure to check the logs for encoding error warnings the first time you run the eNodeB.

Adding New SIBs

The yateenb module schedules all SIBs Type 2 and higher in a single SI Message, with the same periodicity.

To add a new SIB type <N> to the eNodeB:

  • Create the new XML file "enb-sib<N>.xml" in /usr/share/yate/scripts.
  • Define a parameter SibList in yateenb-custom.conf that list all of the SIBs (above SIB Type 2) that are to be used.
    • The form for the SibList parameter is "sibType3 sibType4", etc.
    • The presence of SIB Types 1 and 2 is implied, so those do not appear in the list.

Example

For example, to add a simple SIB Type 4 with one neighbor, define a new file enb-sib4.xml with this content:

<sib4>
    <intraFreqNeighCellList>
        <IntraFreqNeighCellInfo>
            <!-- These values will be pulled from the configuration when the message is generated -->
            <physCellId>${neighborPhyCellID}</physCellId>
            <q_OffsetCell>dB${neighborOffset}</q_OffsetCell>
        </IntraFreqNeighCellInfo>
    </intraFreqNeighCellList>
</sib4>

and add these line to yateenb-custom.conf:

; List of supported SIBs above Type 2
SibList = sibType3 sibType4
; example neighbor in SIB4
; PHY cell ID
neighborPhyCellID = 5
; neighbor power offset in dB
neighborOffset = 0

and edit enb-sib1.tdd.xml and enb-sib1.fdd.xml to update the SIB Mapping Information element:

    <sib_MappingInfo>
        <!-- The SIB list must be updated here and also in the .conf file. -->
        <SIB_Type>sibType3</SIB_Type>
        <SIB_Type>sibType4</SIB_Type>
    </sib_MappingInfo>

Another Example - ETWS (Earthquake & Tsunami Warning System)

For this example, we add two new XML files.

enb-sib10.xml:

<sib10>
        <!-- These bit strings and byte strings are all given in hexadecimal. -->
        <!-- earthquake and tsunami -->
        <messageIdentifier>1101</messageIdentifier>
        <serialNumber>4001</serialNumber>
        <!-- earthquake, alert user, pop-up window -->
        <warningType>0180</warningType>
</sib10>

enb-sib11.xml:

<sib11>
        <!-- These bit strings and byte strings are all given in hexadecimal. -->
        <!-- earthquake and tsunami -->
        <messageIdentifier>1101</messageIdentifier>
        <serialNumber>4001</serialNumber>
        <warningMessageSegmentType>lastSegment</warningMessageSegmentType>
        <warningMessageSegmentNumber>0</warningMessageSegmentNumber>
        <!-- This is a 42-character message "This is a test of ETWS. This is only a test. :)" -->
        <!-- The fields are defined in 3GPP 23.041: 1 byte page number, 82 bytes message content (padded), 2 bytes mesage length (in bytes) -->
        <warningMessageSegment>0154747A0E4ACF416110BD3CA783DE6650917A9DBA4054747A0E4ACF416F373B0F0A83E8E539DD05D2A514D46A3D168341A8D46A3D168341A8D46A3D168341A8D46A3D168341A8D46A3D168341A8D46A3D16002A</warningMessageSegment>
        <!-- GSM 7-bit coding scheme, English language-->
        <dataCodingScheme>01</dataCodingScheme>
</sib11>

and edit enb-sib1.tdd.xml and enb-sib1.fdd.xml to update the SIB Mapping Information element:

    <sib_MappingInfo>
        <!-- SIBs are listed here and in yateenb.conf. -->
        <SIB_Type>sibType3</SIB_Type>
        <SIB_Type>sibType10</SIB_Type>
        <SIB_Type>sibType11</SIB_Type>
    </sib_MappingInfo>

And also set the SIB list in yateenb.conf:

; List of supported SIBs above Type 2
SibList = sibType3 sibType4

Message Size Limitation

All SIBs Type 2 and higher must fit together into a single SI Message in a single subframe using QPSK modulation. The yateenb module will lower the coding rate for SIBs as needed to try to fit all of these SIBs into the subframe. If the SIBs do not fit into the subframe even at the lowest allowed rate, the eNodeB will log a warning at the CRIT level.

Approximate maximum message sizes are:

LTE Bandwidth
(MHz)
Approx Max SI Message
(kbits)
1.4 1.4
3 3.5
5 5.9
10 12
15 18
20 24

The yateenb module may also change the DCI type for SIBs to increase the maximum message size. It will log a message at the CONF level if it does this.

Note: This is the on-line version of the GSM/LTE LabKit AppNote no. 2/2018-02-08.