2018-03-06 16:13:13 +00:00
|
|
|
[[trx_if]]
|
|
|
|
== TRX Manager UDP socket interface
|
|
|
|
|
2019-07-25 15:37:37 +00:00
|
|
|
This is the protocol used between `osmo-trx` (the transceiver) and
|
|
|
|
`osmo-bts-trx` (the BTS or core).
|
2018-03-06 16:13:13 +00:00
|
|
|
|
2019-07-25 15:37:37 +00:00
|
|
|
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.
|
2018-03-06 16:13:13 +00:00
|
|
|
|
2018-09-20 13:02:03 +00:00
|
|
|
[[trx_if_clock_ind]]
|
2018-03-06 16:13:13 +00:00
|
|
|
=== Indications on the Master Clock Interface
|
|
|
|
|
2019-07-25 15:37:37 +00:00
|
|
|
The master clock interface is output only (uplink, from the radio to the BTS).
|
2018-03-06 16:13:13 +00:00
|
|
|
Messages are "indications".
|
|
|
|
|
2019-07-25 15:37:37 +00:00
|
|
|
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.
|
2018-03-06 16:13:13 +00:00
|
|
|
----
|
|
|
|
IND CLOCK <totalFrames>
|
|
|
|
----
|
|
|
|
|
2018-09-20 13:02:03 +00:00
|
|
|
[[trx_if_control]]
|
2019-07-25 15:37:37 +00:00
|
|
|
=== TRXC protocol
|
2018-03-06 16:13:13 +00:00
|
|
|
|
2019-07-25 15:37:37 +00:00
|
|
|
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.
|
2018-03-06 16:13:13 +00:00
|
|
|
|
2019-07-25 15:37:37 +00:00
|
|
|
Every command is structured this way:
|
2018-03-06 16:13:13 +00:00
|
|
|
----
|
|
|
|
CMD <cmdtype> [params]
|
|
|
|
----
|
|
|
|
The `<cmdtype>` is the actual command.
|
|
|
|
Parameters are optional depending on the commands type.
|
2019-07-25 15:37:37 +00:00
|
|
|
|
2018-03-06 16:13:13 +00:00
|
|
|
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>
|
|
|
|
----
|
|
|
|
|
2019-07-25 15:37:37 +00:00
|
|
|
`POWERON` starts the transmitter and starts the demodulator. Initial power
|
2018-03-06 16:13:13 +00:00
|
|
|
level is very low. 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
|
2019-07-25 15:37:37 +00:00
|
|
|
already on, it answers successfully to this command.
|
2018-03-06 16:13:13 +00:00
|
|
|
----
|
|
|
|
CMD POWERON
|
|
|
|
RSP POWERON <status>
|
|
|
|
----
|
|
|
|
|
|
|
|
`SETPOWER` sets output power in dB wrt full scale.
|
|
|
|
This command fails if the transmitter and receiver are not running.
|
|
|
|
----
|
|
|
|
CMD SETPOWER <dB>
|
|
|
|
RSP SETPOWER <status> <dB>
|
|
|
|
----
|
|
|
|
|
|
|
|
`ADJPOWER` adjusts power by the given dB step. Response returns resulting power
|
|
|
|
level wrt full scale. This command fails if the transmitter and receiver are not
|
|
|
|
running.
|
|
|
|
----
|
|
|
|
CMD ADJPOWER <dBStep>
|
|
|
|
RSP ADJPOWER <status> <dBLevel>
|
|
|
|
----
|
|
|
|
|
|
|
|
==== 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
|
|
|
|
|
2019-07-25 15:37:37 +00:00
|
|
|
`SETSLOT` sets the format of a given uplink timeslot in the ARFCN.
|
2018-03-06 16:13:13 +00:00
|
|
|
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>
|
|
|
|
----
|
|
|
|
|
2019-07-25 15:37:37 +00:00
|
|
|
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
|
|
|
|
|===
|
|
|
|
|
2019-07-25 17:06:53 +00:00
|
|
|
==== 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 <timeslot> <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.
|
|
|
|
|
2019-07-25 15:37:37 +00:00
|
|
|
=== TRXD protocol
|
2018-03-06 16:13:13 +00:00
|
|
|
|
|
|
|
Messages on the data interface carry one radio burst per UDP message.
|
|
|
|
|
2019-07-25 15:37:37 +00:00
|
|
|
==== Uplink Data Burst
|
2018-03-06 16:13:13 +00:00
|
|
|
|
2019-07-25 17:06:53 +00:00
|
|
|
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
|
2018-03-06 16:13:13 +00:00
|
|
|
[packetdiag]
|
|
|
|
----
|
|
|
|
{
|
|
|
|
colwidth = 32
|
|
|
|
node_height = 40
|
|
|
|
|
2019-07-25 17:06:53 +00:00
|
|
|
0-3: VER(0)
|
2019-07-25 15:37:37 +00:00
|
|
|
4: RES
|
|
|
|
5-7: TN
|
|
|
|
8-39: FN
|
|
|
|
40-47: RSSI
|
|
|
|
48-63: TOA256
|
|
|
|
64-95: ...Payload...
|
|
|
|
96-97: PAD
|
2018-03-06 16:13:13 +00:00
|
|
|
}
|
|
|
|
----
|
|
|
|
|
2019-07-25 17:06:53 +00:00
|
|
|
.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...
|
|
|
|
}
|
|
|
|
----
|
|
|
|
|
2019-07-25 15:37:37 +00:00
|
|
|
VER: 4 bits::
|
2019-07-25 17:06:53 +00:00
|
|
|
TRXD header version, v0 and v1 are specified so far.
|
2019-07-25 15:37:37 +00:00
|
|
|
|
|
|
|
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.
|
2018-03-06 16:13:13 +00:00
|
|
|
|
2019-07-25 15:37:37 +00:00
|
|
|
TOA256: 16 bits (2 bytes)::
|
|
|
|
Timing of Arrival in units of 1/256 of symbol, big endian.
|
2018-03-06 16:13:13 +00:00
|
|
|
|
2019-07-25 17:06:53 +00:00
|
|
|
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.
|
|
|
|
|
2019-07-25 15:37:37 +00:00
|
|
|
Payload: 148 bytes for GSM, 444 bytes for EDGE::
|
2019-07-25 17:06:53 +00:00
|
|
|
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".
|
2019-07-25 15:37:37 +00:00
|
|
|
|
|
|
|
PAD: 2 bits (optional)::
|
|
|
|
Padding at the end, historical reasons (OpenBTS inheritance). Bits can take any
|
2019-07-25 17:06:53 +00:00
|
|
|
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.
|
2019-07-25 15:37:37 +00:00
|
|
|
|
|
|
|
==== Downlink Data Burst
|
|
|
|
|
|
|
|
.TRXD Downlink data burst message structure
|
2018-03-06 16:13:13 +00:00
|
|
|
[packetdiag]
|
|
|
|
----
|
|
|
|
{
|
|
|
|
colwidth = 32
|
|
|
|
node_height = 40
|
|
|
|
|
2019-07-25 15:37:37 +00:00
|
|
|
0-3: VER
|
|
|
|
4: RES
|
|
|
|
5-7: TN
|
|
|
|
8-39: FN
|
|
|
|
40-47: PWR
|
|
|
|
48-95: ...Payload...
|
2018-03-06 16:13:13 +00:00
|
|
|
}
|
|
|
|
----
|
|
|
|
|
2019-07-25 15:37:37 +00:00
|
|
|
VER: 4 bits::
|
2019-07-25 17:06:53 +00:00
|
|
|
TRXD header version, v0 and v1 are specified so far.
|
2019-07-25 15:37:37 +00:00
|
|
|
|
|
|
|
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).
|