[[trx_if]] == TRX Manager UDP socket interface This is the protocol used between `osmo-trx` (the transceiver) and `osmo-bts-trx` (the BTS or core). Each TRX Manager UDP socket interface represents a single transceiver (ARFCN). Each of these channels is a pair of UDP sockets, one for control (`TRXC`) and one for data (`TRXD`). Additionally, there's a separate global socket managing the Master Clock Interface, shared among all channels. Given a base port `B` (5700), and a set of channels `0..N`, the ports related to a channel `0 <= X <= N` are: * The Master clock interface is located on port `P=B`. * The `TRXC` interface for channel `X` is located on port `P=B+2X+1` * The `TRXD` interface for channel `X` is located on port `P=B+2X+2`. The corresponding interface for every socket is at `P+100` on the BTS side. [[trx_if_clock_ind]] === Indications on the Master Clock Interface The master clock interface is output only (uplink, from the radio to the BTS). Messages are "indications". CLOCK gives the current value of the transceiver clock to be used by the BTS. This message is usually sent around once per second (217 GSM frames), but can be sent at any time. The clock value is NOT the current transceiver time. It is a time setting that the BTS should use to give better packet arrival times. The initial clock value is taken randomly, and then increased over time as the transceiver submits downlink packets to the radio. ---- IND CLOCK ---- [[trx_if_control]] === TRXC protocol The per-ARFCN control interface uses a command-response protocol. Each command has a corresponding response. Commands are sent in downlink direction (BTS -> TRX), and responses are sent in uplink direction (TRX -> BTS). Commands and responses are NULL-terminated ASCII strings. Every command is structured this way: ---- CMD [params] ---- The `` is the actual command. Parameters are optional depending on the commands type. Every response is of the form: ---- RSP [result] ---- The `` is 0 for success and a non-zero error code for failure. Successful responses may include results, depending on the command type. ==== Power Control `POWEROFF` shuts off transmitter power and stops the demodulator. ---- CMD POWEROFF RSP POWEROFF ---- `POWERON` starts the transmitter and starts the demodulator. Initial power level is by default very low, unless set explicitly by `SETPOWER`/`ADJPOWER` beforehand while in `POWEROFF` state. This command fails if the transmitter and receiver are not yet tuned. This command fails if the transmit or receive frequency creates a conflict with another ARFCN that is already running. If the transceiver is already on, it answers successfully to this command. ---- CMD POWERON RSP POWERON ---- `NOMTXPOWER` is used by the BTS to retrieve the nominal output transmit power of the transceiver. `SETPOWER/ADJPOWER` attenuations (dB) are expected to be applied based on this value (dBm). ---- CMD NOMTXPOWER RSP NOMTXPOWER ---- `SETPOWER` sets transmit power attenuation wrt the nominal transmit power of the transceiver, in dB. ---- CMD SETPOWER RSP SETPOWER ---- `ADJPOWER` adjusts by the given dB the transmit power attenuation of the transceiver. Response returns resulting transmit power attenuation wrt the nominal transmit power of the transceiver. ---- CMD ADJPOWER RSP ADJPOWER ---- `RFMUTE` locks the RF transceiver, hence disabling emission and reception of information on Air interface of the channel associated to the TRXC connection the command is sent on. Parameter with value of `1` is used to mute, and value of `0` is used to unmute. ---- CMD RFMUTE <1|0> RSP RFMUTE <1|0> ---- ==== Tuning Control `RXTUNE` tunes the receiver to a given frequency in kHz. This command fails if the receiver is already running. (To re-tune you stop the radio, re-tune, and restart.) This command fails if the transmit or receive frequency creates a conflict with another ARFCN that is already running. ---- CMD RXTUNE RSP RXTUNE ---- `TXTUNE` tunes the transmitter to a given frequency in kHz. This command fails if the transmitter is already running. (To re-tune you stop the radio, re-tune, and restart.) This command fails if the transmit or receive frequency creates a conflict with another ARFCN that is already running. ---- CMD TXTUNE RSP TXTUNE ---- ==== Training Sequence configuration The usual way to configure all timeslots at once involves sending of the 'SETTSC' command with a desired Training Sequence Code ``: ---- CMD SETTSC CMD SETTSC ---- This command instructs the transceiver to use the given Training Sequence Code from the TSC set 1 (see 3GPP TS 45.002, table 5.2.3a) for Normal Burst detection on the receive path. It does not affect the transmit path because bursts coming from the BTS do contain the Training Sequence bits. ==== Timeslot Control `SETSLOT` sets the format of a given uplink timeslot in the ARFCN. The `` indicates the timeslot of interest. The `` indicates the type of channel that occupies the timeslot. A chantype of zero indicates the timeslot is off. ---- CMD SETSLOT RSP SETSLOT ---- Here's the list of channel combinations and related values (``): .List of channel combinations and related values (``) [options="header"] |=== | value | Channel Combination |0| Channel is transmitted, but unused |1| TCH/FS |2| TCH/HS, idle every other slot |3| TCH/HS |4| Downlink: FCCH + SCH + CCCH + BCCH, Uplink: RACH |5| Downlink: FCCH + SCH + CCCH + BCCH + SDCCH/4 + SACCH/4, Uplink: RACH+SDCCH/4 |6| Downlink: CCCH+BCCH, Uplink: RACH |7| SDCCH/8 + SACCH/8 |8| TCH/F + FACCH/F + SACCH/M |9| TCH/F + SACCH/M |10| TCH/FD + SACCH/MD |11| PBCCH+PCCCH+PDTCH+PACCH+PTCCH |12| PCCCH+PDTCH+PACCH+PTCCH |13| PDTCH+PACCH+PTCCH |=== ===== Multiple Training Sequences (optional) For some setups it's insufficient to have a single Training Sequence Code assigned to all timeslots of a transceiver. It may be required to use different TSCs for some (or even all) timeslots. This can be achieved by sending 'SETSLOT' command with additional arguments: ---- CMD SETSLOT [ C/S ] RSP SETSLOT [ C/S ] ---- where `` is a Training Sequence Code from TSC set ``. NOTE: The numbering of both Training Sequence code and set shall be the same as in 3GPP TS 45.002, e.g. `C0S1` corresponds to the first sequence in the first TSC set for a chosen modulation type. Set number 0 (`S0`) does not exist in the specs. .Example: configuring timeslot 4 to use TCH/F and TSC 7 from set 1 ---- CMD SETSLOT 4 1 C7/S1 RSP SETSLOT 0 4 1 C7/S1 ---- Unless explicitly configured as described above, all timeslots will be using the default Training Sequence Code and set configured with the 'SETTSC' command. ===== VAMOS enabled channel combinations (optional) The BTS may at any time re-configure channel combination of a timeslot (primarily during channel activation) to activate or deactivate VAMOS mode in the transceiver. For this purpose, the following additional channel combinations shall be used: .List of VAMOS enabled channel combinations and related values [options="header"] |=== | value | Channel Combination |VFF| V0(TCH/F) & V1(TCH/F), 2 channels total |VHH| V0(TCH/H0) & V1(TCH/H0) + V0(TCH/H1) & V1(TCH/H1), 4 channels total |VFH| V0(TCH/F) & V1(TCH/H0) + V0(TCH/F) & V1(TCH/H1), 3 channels total |HVHH| TCH/H0 + V0(TCH/H1) & V1(TCH/H1), 3 channels total (mixed) |=== where both `V0` and `V1` define a _VAMOS pair_. Symbols `&` and `+` indicate simultaneous and sequential transmission in the TDMA domain respectively. Therefore a combination `V0(a) & V1(b)` indicates that both channels `a` and `b` are simultaneously active during a timeslot period. .Example: `VFF` in time domain (2 channels) ---- MS1: | V0(TCH/F) | V0(TCH/F) | V0(TCH/F) | V0(TCH/F) | ... -----+-----------+-----------+-----------+-----------+------------> TDMA frames MS2: | V1(TCH/F) | V1(TCH/F) | V1(TCH/F) | V1(TCH/F) | ... ---- .Example: `VHH` in time domain (4 channels) ---- MS1: | V0(TCH/H0) | | V0(TCH/H0) | | ... MS2: | | V0(TCH/H1) | | V0(TCH/H1) | ... -----+------------+------------+------------+------------+--------> TDMA frames MS3: | V1(TCH/H0) | | V1(TCH/H0) | | ... MS4: | | V1(TCH/H1) | | V1(TCH/H1) | ... ---- .Example: `VFH` in time domain (3 channels) ---- MS1: | V0(TCH/F) | V0(TCH/F) | V0(TCH/F) | V0(TCH/F) | ... -----+------------+------------+------------+------------+--------> TDMA frames MS2: | V1(TCH/H0) | | V1(TCH/H0) | | ... MS3: | | V1(TCH/H1) | | V1(TCH/H1) | ... ---- .Example: `HVHH` in time domain (3 channels) ---- MS1: | TCH/H0 | | TCH/H0 | | ... MS2: | | V0(TCH/H1) | | V0(TCH/H1) | ... -----+------------+------------+------------+------------+--------> TDMA frames MS3: | | V1(TCH/H1) | | V1(TCH/H1) | ... ---- NOTE: Combination `HVHH` is special, because it allows the network to multiplex a legacy user device (`MS1`) with a pair of VAMOS capable devices (`MS2` and `MS3`) on the same timeslot, so the former (`MS1`) is not required to support the new orthogonal training sequences nor AQPSK modulation on Downlink. For all VAMOS specific channel combinations, it's *required* to specify Training Sequence codes and the corresponding TSC sets (see 3GPP TS 45.002, table 5.2.3e for more details on TSC set selection): .Example: configuring a timeslot to use `VFF` combination ---- CMD SETSLOT VFF C0/S1 <1> C0/S2 <2> RSP SETSLOT VFF C0/S1 C0/S2 ---- <1> V0(TCH/F) is configured to use TSC 0 from set 1 (table 5.2.3a) <2> V1(TCH/F) is configured to use TSC 0 from set 2 (table 5.2.3b) .Example: configuring a timeslot to use `VHH` combination ---- CMD SETSLOT VHH C1/S3 <1> C1/S4 <2> RSP SETSLOT VHH C1/S3 C1/S4 ---- <1> V0(TCH/H0) and V0(TCH/H1) are configured to use TSC 1 from set 3 (table 5.2.3c) <2> V1(TCH/H0) and V1(TCH/H1) are configured to use TSC 1 from set 4 (table 5.2.3d) .Example: configuring a timeslot to use `VFH` combination ---- CMD SETSLOT VFH C2/S1 <1> C2/S4 <2> RSP SETSLOT VFH C2/S1 C2/S4 ---- <1> V0(TCH/F) is configured to use TSC 2 from set 1 (table 5.2.3a) <2> V1(TCH/H0) and V1(TCH/H1) are configured to use TSC 2 from set 4 (table 5.2.3d) .Example: configuring a timeslot to use `HVHH` combination ---- CMD SETSLOT HVHH C0/S1 <1> C0/S1 <2> C0/S2 <3> RSP SETSLOT HVHH C0/S1 C0/S1 C0/S2 ---- <1> Legacy TCH/H0 is configured to use TSC 0 from set 1 (table 5.2.3a) <2> V0(TCH/H1) is configured to use TSC 0 from set 1 (table 5.2.3a) <3> V1(TCH/H1) is configured to use TSC 0 from set 2 (table 5.2.3b) NOTE: Using Training Sequences from the same set for a _VAMOS pair_ is not permitted! In the example for `HVHH`, legacy TCH/H0 does not belong to a _VAMOS pair_, so it can be configured to use any sequence from any set. [[trx_if_pdu_version_nego]] ==== TRXD header version negotiation Messages on DATA interface may have different formats, defined by a version number, which can be negotiated on the control interface. By default, the Transceiver will use the legacy header version (0). See <>. The format negotiation can be initiated by the BTS using 'SETFORMAT' command. If the requested version is not supported by the transceiver, status code of the response message should indicate a preferred (basically, the latest) version. The format of this message is the following: ---- CMD SETFORMAT RSP SETFORMAT ---- where: * `` is the requested version (suggested by the BTS), * `` is either the applied version if matches ``, or a preferred version if `` is not supported. If the transceiver indicates `` different than ``, the BTS is supposed to re-initiate the version negotiation using the suggested ``. For example: ---- BTS -> TRX: CMD SETFORMAT 2 BTS <- TRX: RSP SETFORMAT 1 2 BTS -> TRX: CMD SETFORMAT 1 BTS <- TRX: RSP SETFORMAT 1 1 ---- If no suitable `` is found, or the `` is incorrect, the status code in the response shall be `-1`. As soon as `` matches `` in the response, the process of negotiation is complete. Changing the header version is supposed to be done before `POWERON`, but can be also done afterwards. === TRXD protocol PDUs on the data interface carry one or multiple radio bursts per UDP message. Two kinds of such messages exist: * `TRX -> L1` (from transceiver to the L1): Uplink messages received from the MS, * `L1 -> TRX` (from the L1 to transceiver): Downlink messages sent to the MS. Regardless of the origin, all PDUs have the following common structure: .General message format [packetdiag] ---- { colwidth = 32 node_height = 40 0-3: VER 4: RFU [rotate = 270] 5-7: TN 8-63: ... Specific fields ... 64-95: Burst bits [colheight = 3] } ---- VER: 4 bits:: TRXD header version, common for both `TRX -> L1` and `L1 -> TRX` directions. TN: 3 bits:: TDMA timeslot number. RFU: 1 bit:: Reserved, shall be 0. It can be used in the future to extend the TDMA TN range to (0..15), in case anybody would need to transfer UMTS bursts. FN: 32 bits (4 bytes):: TDMA frame number, big endian. Specific fields: variable length:: This part depends on the origin of a message and the header version. See below. Burst bits: variable length:: The actual bit sequence of a burst, where each bit takes one octet. Depending on the origin, all bits in the sequence are either _soft-bits_ (from demodulator) or _hard-bits_ (to the modulator). Length of the sequence depends on modulation type of the burst. [[trx_if_pdu_versioning]] ==== PDU versioning The format of a PDU, i.e. presence and ordering of certain fields, is determined by the version number indicated in the first octet. This is usually referred as `TRXDvN`, where `N` is the version number (e.g. TRXDv0 or TRXDv1). A version number indicates the message format to be used for both directions: `TRX -> L1` and `L1 -> TRX`. The same version shall be used for all messages in both directions, mixing in any way is not permitted. The version negotiation is optionally initiated by the `L1` on the control interface, and expected to be performed before starting the transceiver (i.e. sending 'POWERON' command). See <>. The current header allows to distinguish up to 16 different versions. The following versions are defined so far: * TRXDv0 - initial version of TRXD protocol, inherited as-is from OpenBTS project. * TRXDv1 (proposed in July 2019): ** Introduced the concept of protocol versioning; ** Introduced NOPE / IDLE indications; ** New field: MTS (Modulation and Training Sequence); ** New field: C/I (Carrier-to-interface) ratio; ** Downlink messages mostly unchanged. * TRXDv2 (proposed in January 2021): ** Introduced the concept of burst batching (many bursts in one message); ** Changed the field ordering (facilitating aligned access); ** New field: batching indicator; ** New field: SCPIR for VAMOS. ==== Uplink Data Burst Uplink data burst message structure differs from version 0 to 1. Basically, version 1 contains an extended header with regards to version 0, and the final padding existence is completely dropped. .TRXDv0 Uplink data burst message structure [packetdiag] ---- { colwidth = 32 node_height = 40 0-3: VER(0) 4: RES [rotate = 270] 5-7: TN 8-39: FN 40-47: RSSI 48-63: TOA256 64-95: Soft-bits 96-111: PAD } ---- .TRXDv1 Uplink data burst message structure [packetdiag] ---- { colwidth = 32 node_height = 40 0-3: VER(1) 4: RES [rotate = 270] 5-7: TN 8-39: FN 40-47: RSSI 48-63: TOA256 64-71: MTS 72-87: C/I 88-127: Soft-bits } ---- .TRXDv1 NOPE / IDLE indication message structure [packetdiag] ---- { colwidth = 32 node_height = 40 0-3: VER(1) 4: RES [rotate = 270] 5-7: TN 8-39: FN 40-47: RSSI 48-63: TOA256 64-71: MTS (NOPE.ind) 72-87: C/I } ---- .TRXDv2 Uplink message structure [packetdiag] ---- { colwidth = 32 node_height = 40 0-3: VER(2) 4: RES [rotate = 270] 5-7: TN 8-15: MTS 16: BATCH [rotate = 270] 17-23: SPARE (0) 24-31: RSSI 32-47: TOA256 48-63: C/I 64-95: FN 96-127: Soft-bits [colheight = 3] } ---- .TRXDv2 Uplink message structure (batched part) [packetdiag] ---- { colwidth = 32 node_height = 40 0-3: SPARE (0) 4: RES [rotate = 270] 5-7: TN 8-15: MTS 16: BATCH [rotate = 270] 17-23: SPARE (0) 24-31: RSSI 32-47: TOA256 48-63: C/I 64-95: Soft-bits [colheight = 3] } ---- RSSI: 8 bits (1 byte):: Received Signal Strength Indication in -dBm, encoded without the negative sign. TOA256: 16 bits (2 bytes):: Timing of Arrival in units of 1/256 of symbol, big endian. MTS: 8 bits (1 byte):: Contains the Modulation and Training Sequence information. See <> for more information on the encoding. C/I: 16 bits (2 bytes):: Contains the Carrier-to-Interference ratio in centiBels, big endian. The C/I value is computed from the training sequence of each burst, where the "ideal" training sequence is compared to the actual training sequence and the result expressed in centiBels. Soft-bits: 148 bytes for GSM, 444 bytes for EDGE:: Contains the uplink burst. Unlike the downlink bursts, the uplink bursts are designated using the soft-bits notation, so the receiver can indicate its assurance from 0 to -127 that a given bit is 1, and from 0 to +127 that a given bit is 0. The Viterbi algorithm allows to approximate the original sequence of hard-bits (1 or 0) using these values. Each soft-bit (-127..127) of the burst is encoded as an unsigned value in range (0..255) respectively using the constant shift. This way: * 0 -> definite "0" * 255 -> definite "1". PAD: 2 bytes (optional):: Padding at the end, historical reasons (OpenBTS inheritance). Bits can take any value, but 0 is preferred. Only expected on TRXDv0 headers. [[coding-mts]] ===== Coding of MTS: Modulation and Training Sequence info 3GPP TS 45.002 version 15.1.0 defines several modulation types, and a few sets of training sequences for each type. The most common are GMSK and 8-PSK (which is used in EDGE). .MTS field structure ---- +-----------------+---------------------------------------+ | 7 6 5 4 3 2 1 0 | bit numbers (value range) | +-----------------+---------------------------------------+ | X . . . . . . . | IDLE / nope frame indication (0 or 1) | +-----------------+---------------------------------------+ | . X X X X . . . | Modulation, TS set number (see below) | +-----------------+---------------------------------------+ | . . . . . X X X | Training Sequence Code (0..7) | +-----------------+---------------------------------------+ ---- IDLE / nope frame indication:: The bit number 7 (MSB) is set to high when either nothing has been detected, so the BTS scheduler keeps processing bursts without gaps, or during IDLE frames, so the current noise levels can be delivered. Other bits are ignored, and should be set to low (`0`) in this case. The field "Soft-bits" is omited. Modulation and TS set number:: GMSK has 4 sets of training sequences (see tables 5.2.3a-d), while 8-PSK (see tables 5.2.3f-g) and the others have 2 sets. Access and Synchronization bursts also have several synchronization sequences. .Modulation and TS set number ---- +-----------------+---------------------------------------+ | 7 6 5 4 3 2 1 0 | bit numbers (value range) | +-----------------+---------------------------------------+ | . 0 0 X X . . . | GMSK, 4 TS sets (0..3) | +-----------------+---------------------------------------+ | . 0 1 0 X . . . | 8-PSK, 2 TS sets (0..1) | +-----------------+---------------------------------------+ | . 0 1 1 0 . . . | GMSK, Access Burst (see note) | +-----------------+---------------------------------------+ | . 0 1 1 1 . . . | RFU (Reserved for Future Use) | +-----------------+---------------------------------------+ | . 1 0 0 X . . . | 16QAM, 2 TS sets (0..1) | +-----------------+---------------------------------------+ | . 1 0 1 X . . . | 32QAM, 2 TS sets (0..1) | +-----------------+---------------------------------------+ | . 1 1 X X . . . | AQPSK (Downlink), 4 TS sets (0..3) | +-----------------+---------------------------------------+ ---- NOTE: A radio block on PDCH is carried by the sequence of four Normal Bursts. The one exception is a special radio block occasionally used on the Uplink consisting of a sequence of four Access Bursts (see 3GPP TS 44.060). The transceiver shall use `0110` as the modulation type to indicate that. Training Sequence Code:: The Training Sequence Code identifies the Training Sequence of a received burst. The value of this field corresponds to one of the sequences defined in 3GPP TS 45.002, section 5.2, and depends on the actual modulation and a TS set indicated by the preceding bits. ==== Downlink Data Burst .TRXDv0 and TRXDv1 Downlink data burst message structure [packetdiag] ---- { colwidth = 32 node_height = 40 0-3: VER 4: RES [rotate = 270] 5-7: TN 8-39: FN 40-47: PWR 48-95: Hard-bits } ---- .TRXDv2 Downlink data burst message structure [packetdiag] ---- { colwidth = 32 node_height = 40 0-3: VER 4: RES [rotate = 270] 5-7: TN 8-15: MTS 16: BATCH [rotate = 270] 17-23: SPARE (0) 24-31: PWR 32-63: FN 64-95: Hard-bits [colheight = 3] } ---- .TRXDv2 Downlink data burst message structure (batched part) [packetdiag] ---- { colwidth = 32 node_height = 40 0-3: SPARE (0) 4: RES [rotate = 270] 5-7: TN 8-15: MTS 16: BATCH [rotate = 270] 17-23: SPARE (0) 24-31: PWR 32-63: Hard-bits [colheight = 3] } ---- .TRXDv2 Downlink data burst message structure for AQPSK [packetdiag] ---- { colwidth = 32 node_height = 40 0-3: VER 4: RES [rotate = 270] 5-7: TN 8-15: MTS 16: BATCH [rotate = 270] 17-19: SPARE (0) 20-23: SCPIR 24-31: PWR 32-63: FN 64-95: Hard-bits for V0/V1 [colheight = 3] } ---- .TRXDv2 Downlink data burst message structure (batched part) for AQPSK [packetdiag] ---- { colwidth = 32 node_height = 40 0-3: SPARE (0) 4: RES [rotate = 270] 5-7: TN 8-15: MTS 16: BATCH [rotate = 270] 17-19: SPARE (0) 20-23: SCPIR 24-31: PWR 32-63: Hard-bits for V0/V1 [colheight = 3] } ---- PWR: 8 bits (1 byte):: Contains the relative (to the full-scale amplitude) transmit power *reduction* in dB. The absolute value is set on the control interface, so the resulting power is calculated as follows: `full_scale - (absolute_red + relative_red)`. SCPIR: 4 bits:: SCPIR (Subchannel Power Imbalance Ratio) - the ratio of power between Q and I channels for a VAMOS pair. Value range: 0 .. 10. This field shall be present when `MTC` field indicates the use of _AQPSK_ modulation. Otherwise all bits shall be set to 0. Hard-bits: 148 bytes for GSM, 444 bytes for EDGE:: Contains the downlink burst. Each hard-bit (1 or 0) of the burst is represented using one byte (0x01 or 0x00 respectively). Hard-bits for V0/V1: 148 bytes each, 296 bytes total:: This field contains two sequences of hard-bits (148 bytes each) for an _AQPSK_ moduleted burst (VAMOS mode). The two sequences are *not* interleaved: one complete sequence for subscriber `V0` takes the first 148 bytes, then another complete sequence for subscriber `V1` takes the subsequent 148 bytes. [[trx_if_pdu_batching]] ==== Burst batching Starting from TRXDv2, it's possible to combine several bursts into a single PDU - this is called _burst batching_. The purpose of FIXME The ordering of bursts may be different with the only requirement that all _batched_ bursts must belong to the same TDMA frame number indicated in the first part. Thus the following combinations are possible: * one PDU contains bursts of the same TDMA timeslot for all transceivers; * one PDU contains complete TDMA frame with all timeslots: ** either for a single transceiver, ** or for all transceivers.