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

==== 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
|===

==== 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).