Difference between revisions of "GSM/LTE LabKit AppNote: Legba LTE/GSM LabKit easy configuration for IoT tests"

From YateBTS
Jump to: navigation, search
(A 2nd use example + some comments)
(Undo revision 3536 by Iulian.Comanescu (talk))
Line 1: Line 1:
The purpose of this page is to document the format and syntax of XML files for SIB messages in yateenb.
+
The purpose of this page is to document the format and syntax of XML files for SIB messages in [[YateeNB]].
  
 
== Overview ==
 
== Overview ==
System Information Blocks (SIBs) are broadcast messages that advertise the configuration of the eNodeB.
+
'''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 YateeNB module generates the binary content of its SIBs from XML files.
 
The module parses these files whenever it is started or restarted.
 
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.
+
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 [https://en.wikipedia.org/wiki/Abstract_Syntax_Notation_One XER-UPER] encoder for these files is generated directly from the ASN.1 source code in the specifications.
 
The [https://en.wikipedia.org/wiki/Abstract_Syntax_Notation_One 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.
+
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:
+
For SIB Type 1, there are two possible XML files, one for FDD and one for TDD:
 
* enb-sib1.fdd.xml
 
* enb-sib1.fdd.xml
 
* enb-sib1-tdd.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.
+
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.
+
In a LabKit 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.
+
'''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 ==
 
== 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.
+
The XML encoder can set the values of SIB information elements from the '''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.
 
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:
+
For example, here is the standard '''FDD SIB Type 1 XML file''' distributed with YateeNB:
<source lang="xml">
+
<pre lang="xml">
 
<systemInformationBlockType1>
 
<systemInformationBlockType1>
 
   <cellAccessRelatedInfo>
 
   <cellAccessRelatedInfo>
Line 60: Line 60:
 
   <systemInfoValueTag>0</systemInfoValueTag>
 
   <systemInfoValueTag>0</systemInfoValueTag>
 
</systemInformationBlockType1>
 
</systemInformationBlockType1>
</source>
+
</pre>
  
In this example, the following elements take their values from the yateenb module configuration:
+
In this example, the following elements take their values from the YateeNB module configuration:
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 84: Line 84:
 
|}
 
|}
  
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.
+
These particular configuration parameters are defined in '''YateeNB.conf''' by the [[Mobile Management Interface|MMI]] or [[Local Management Interface|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.
+
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 only restrictions are:
* The parameter name does not conflict with any existing yateenb parameter.
+
* 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.
 
* The new element or element value does not conflict with the actual implementation of the eNodeB.
  
Line 95: Line 95:
 
to something like
 
to something like
 
  <cellBarred>${cellBarredParam}</cellBarred>
 
  <cellBarred>${cellBarredParam}</cellBarred>
and then add some lines like this to yateenb-custom.conf:
+
and then add some lines like this to YateeNB-custom.conf:
 
  ; Cell Barred configuration in SIB1.
 
  ; Cell Barred configuration in SIB1.
 
  ; Valid values are "notBarred" and "barred".
 
  ; Valid values are "notBarred" and "barred".
 
  callBarredParam notBarred
 
  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:''' 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.
+
'''Note:''' Parameters that are hard-coded in the SIBs provide reasonable default values in most cases. Changing them '''may degrade performance'''.
  
 
== Error Checking ==
 
== Error Checking ==
The yateenb module logs XML/SIB encoding errors the CRIT level.
+
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.
 
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 ==
 
== Adding New SIBs ==
The yateenb module schedules all SIBs Type 2 and higher in a single SI Message, with the same periodicity.
+
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:
 
To add a new SIB type <N> to the eNodeB:
* Create the new XML file "enb-sib<N>.xml" in /usr/share/yate/scripts.
+
* 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.
+
* 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 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.
 
** The presence of SIB Types 1 and 2 is implied, so those do not appear in the list.
  
 
=== Example ===
 
=== Example ===
For example, to add a simple SIB Type 4 with one neighbor, define a new file enb-sib4.xml with this content:
+
For example, to add '''a simple SIB Type 4 with one neighbor''', define a new file '''enb-sib4.xml''' with this content:
<source lang="xml">
+
<pre lang="xml">
 
<sib4>
 
<sib4>
 
     <intraFreqNeighCellList>
 
     <intraFreqNeighCellList>
 
         <IntraFreqNeighCellInfo>
 
         <IntraFreqNeighCellInfo>
            <!-- These values will be pulled from the configuration when the message is generated -->
 
 
             <physCellId>${neighborPhyCellID}</physCellId>
 
             <physCellId>${neighborPhyCellID}</physCellId>
 
             <q_OffsetCell>dB${neighborOffset}</q_OffsetCell>
 
             <q_OffsetCell>dB${neighborOffset}</q_OffsetCell>
Line 129: Line 128:
 
     </intraFreqNeighCellList>
 
     </intraFreqNeighCellList>
 
</sib4>
 
</sib4>
</source>
+
</pre>
  
and add these line to yateenb-custom.conf:
+
and add these line to YateeNB-custom.conf:
 
  ; List of supported SIBs above Type 2
 
  ; List of supported SIBs above Type 2
 
  SibList = sibType3 sibType4
 
  SibList = sibType3 sibType4
Line 141: Line 140:
  
 
and edit enb-sib1.tdd.xml and enb-sib1.fdd.xml to update the SIB Mapping Information element:
 
and edit enb-sib1.tdd.xml and enb-sib1.fdd.xml to update the SIB Mapping Information element:
<source lang="xml">
+
<pre lang="xml">
 
     <sib_MappingInfo>
 
     <sib_MappingInfo>
        <!-- The SIB list must be updated here and also in the .conf file. -->
 
 
         <SIB_Type>sibType3</SIB_Type>
 
         <SIB_Type>sibType3</SIB_Type>
 
         <SIB_Type>sibType4</SIB_Type>
 
         <SIB_Type>sibType4</SIB_Type>
 
     </sib_MappingInfo>
 
     </sib_MappingInfo>
</source>
 
 
=== Another Example - ETWS ===
 
 
For this example, we add two new XML files.
 
 
enb-sib10.xml:
 
<source lang='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>
 
</source>
 
 
enb-sib11.xml:
 
<source lang='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>
 
</source>
 
 
and edit enb-sib1.tdd.xml and enb-sib1.fdd.xml to update the SIB Mapping Information element:
 
<source lang='xml'>
 
    <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>
 
</source>
 
 
And also set the SIB list in yateenb.conf:
 
<pre>
 
; List of supported SIBs above Type 2
 
SibList = sibType3 sibType4
 
 
</pre>
 
</pre>
  
 
=== Message Size Limitation ===
 
=== Message Size Limitation ===
All SIBs Type 2 and higher must fit together into a single SI Message in a single subframe using QPSK modulation.
+
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.
+
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.
 
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:
+
'''Approximate''' maximum message sizes are:
 
{| class="wikitable"
 
{| class="wikitable"
 
! LTE Bandwidth <br/> (MHz) !! Approx Max SI Message <br/> (kbits)
 
! LTE Bandwidth <br/> (MHz) !! Approx Max SI Message <br/> (kbits)
Line 220: Line 169:
 
|}
 
|}
  
The yateenb module may also change the DCI type for SIBs to increase the maximum message size.
+
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.
 
It will log a message at the CONF level if it does this.

Revision as of 14:27, 5 February 2018

The purpose of this page is to document the format and syntax of XML files for SIB messages in YateeNB.

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 FDD and one for TDD:

  • 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 LabKit 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 the 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>
            <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>
        <SIB_Type>sibType3</SIB_Type>
        <SIB_Type>sibType4</SIB_Type>
    </sib_MappingInfo>

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.