osmo-gsm-manuals/common/chapters/trx_if.adoc

[[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 <totalFrames>
----

[[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 <cmdtype> [params]
----
The `<cmdtype>` is the actual command.
Parameters are optional depending on the commands type.

Every response is of the form:
----
RSP <cmdtype> <status> [result]
----
The `<status>` 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 <status>
----

`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 <status>
----

`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 <status> <dBm>
----

`SETPOWER` sets transmit power attenuation wrt the nominal transmit power of
the transceiver, in dB.
----
CMD SETPOWER <dB>
RSP SETPOWER <status> <dB>
----

`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 <dBStep>
RSP ADJPOWER <status> <dBLevel>
----

`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 <status> <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 <kHz>
RSP RXTUNE <status> <kHz>
----

`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 <kHz>
RSP TXTUNE <status> <kHz>
----

==== Training Sequence configuration

The usual way to configure all timeslots at once involves sending of the `SETTSC`
command with a desired Training Sequence Code `<tsc>`:
----
CMD SETTSC <tsc>
CMD SETTSC <status> <tsc>
----

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 `<timeslot>` indicates the timeslot of interest.
The `<chantype>` indicates the type of channel that occupies the timeslot.
A chantype of zero indicates the timeslot is off.
----
CMD SETSLOT <timeslot> <chantype>
RSP SETSLOT <status> <timeslot> <chantype>
----

Here's the list of channel combinations and related values (`<chantype>`):

.List of channel combinations and related values (`<chantype>`)
[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 <timeslot> <chantype> [ C<c>/S<s> ]
RSP SETSLOT <status> <timeslot> <chantype> [ C<c>/S<s> ]
----

where `<c>` is a Training Sequence Code from TSC set `<s>`.

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.  TSC 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 neither required to support the new
orthogonal TSC sets nor conform to DARP phase I or II (SAIC support).

For all VAMOS enabled channel combinations, it's *required* to specify Training
Sequence Code and the TSC set values for all multiplexed subscribers.  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 <timeslot> VFF C0/S1 <1> C0/S2 <2>
RSP SETSLOT <status> <timeslot> 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 `VFF` combination (legacy MS)
----
CMD SETSLOT <timeslot> VFF C7/S1 <1> C4/S1 <2>
RSP SETSLOT <status> <timeslot> VFF C7/S1 C4/S1
----
<1> V0(TCH/F) is configured to use TSC 7 from set 1 (table 5.2.3a).
<2> V1(TCH/F) is configured to use TSC 4 from set 1 (table 5.2.3a).

NOTE: Using Training Sequences from the same set for a _VAMOS pair_ (in this example,
`C7/S1 C4/S1`) is not recommended because of their bad cross-correlation properties.
The only exception is when two legacy non-VAMOS capable phones are paired together
and neither of them does support additional TSC sets.

.Example: configuring a timeslot to use `VHH` combination
----
CMD SETSLOT <timeslot> VHH C1/S3 <1> C1/S4 <2>
RSP SETSLOT <status> <timeslot> 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 <timeslot> VFH C2/S1 <1> C2/S4 <2>
RSP SETSLOT <status> <timeslot> 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 <timeslot> HVHH C0/S1 <1> C0/S1 <2> C0/S2 <3>
RSP SETSLOT <status> <timeslot> 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: In the example for `HVHH`, legacy TCH/H0 does not belong to a _VAMOS pair_,
so it can be configured to use any Training Sequence Code without restrictions.

==== TRXD header version negotiation

Messages on DATA interface may have different header 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).

The header 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 <ver_req>
RSP SETFORMAT <ver_resp> <ver_req>
----

where:

* `<ver_req>` is the requested version (suggested by the BTS),
* `<ver_rsp>` is either the applied version if matches `<ver_req>`, or a
  preferred version if `<ver_req>` is not supported.

If the transceiver indicates `<ver_rsp>` different than `<ver_req>`, the BTS is
supposed to re-initiate the version negotiation using the suggested `<ver_rsp>`.
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 `<ver_rsp>` is found, or the `<ver_req>` is incorrect, the status
code in the response shall be `-1`.

As soon as `<ver_rsp>` matches `<ver_req>` 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

Messages on the data interface carry one radio burst per UDP message.

==== 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
	5-7:	TN
	8-39:	FN
	40-47:	RSSI
	48-63:	TOA256
	64-95:	...Payload...
	96-97:	PAD
}
----

.TRXDv1 Uplink data burst message structure
[packetdiag]
----
{
	colwidth = 32
	node_height = 40

	0-3:	VER(1)
	4:	RES
	5-7:	TN
	8-39:	FN
	40-47:	RSSI
	48-63:	TOA256
	64-71:	MTS
	72-87:	C/I
	88-127:	...Payload...
}
----

VER: 4 bits::
TRXD header version, v0 and v1 are specified so far.

TN: 3 bits::
Timeslot number.

RES: 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)::
GSM frame number, big endian.

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 <<coding-mts>>
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.

Payload: 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 bits (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, or
during IDLE frames, so noise levels can be delivered, and avoid clock gaps on
the BTS side. Other bits are ignored, and should be set to low (`0`) in this
case.

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 X . . . | AQPSK, 2 TS sets (0..1)               |
+-----------------+---------------------------------------+
| . 1 0 0 X . . . | 16QAM, 2 TS sets (0..1)               |
+-----------------+---------------------------------------+
| . 1 0 1 X . . . | 32QAM, 2 TS sets (0..1)               |
+-----------------+---------------------------------------+
| . 1 1 X X . . . | RESERVED (0)                          |
+-----------------+---------------------------------------+
----

Training Sequence Code::
The Training Sequence Code used to decode an Access or a Synchronization burst.
This field hence doesn't apply for Normal bursts.

==== Downlink Data Burst

.TRXD Downlink data burst message structure
[packetdiag]
----
{
	colwidth = 32
	node_height = 40

	0-3:	VER
	4:	RES
	5-7:	TN
	8-39:	FN
	40-47:	PWR
	48-95:	...Payload...
}
----

VER: 4 bits::
TRXD header version, v0 and v1 are specified so far.

TN: 3 bits::
Timeslot number.

RES: 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)::
GSM frame number, big endian.

PWR: 8 bits (1 byte)::
Contains the relative (to the full-scale amplitude) transmit power level in dB.
The absolute value is set on the control interface.

Payload: 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).