From 9af4229dbe5829b00ebd9a06575a55d50a6c0613 Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Tue, 6 Mar 2018 17:13:13 +0100 Subject: Introduce chapter trx_if.adoc and add it to OsmoTRX and OsmoBTS This chapter defines the protocol used between osmo-trx and osmo-bts-trx. Most of the text comes originally from osmo-trx.git/README, as it's the only known documentation of the protocol other than the code itself. Change-Id: I56c418eef0f826ae1aadbed5b151fbed241c7885 --- OsmoBTS/osmobts-usermanual.adoc | 3 +- OsmoTRX/osmotrx-usermanual.adoc | 2 + common/chapters/trx_if.adoc | 156 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 160 insertions(+), 1 deletion(-) create mode 100644 common/chapters/trx_if.adoc diff --git a/OsmoBTS/osmobts-usermanual.adoc b/OsmoBTS/osmobts-usermanual.adoc index d746d85..07f88e2 100644 --- a/OsmoBTS/osmobts-usermanual.adoc +++ b/OsmoBTS/osmobts-usermanual.adoc @@ -26,6 +26,8 @@ include::chapters/bts-models.adoc[] include::chapters/architecture.adoc[] +include::../common/chapters/trx_if.adoc[] + include::../common/chapters/control_if.adoc[] include::../common/chapters/port_numbers.adoc[] @@ -35,4 +37,3 @@ include::../common/chapters/bibliography.adoc[] include::../common/chapters/glossary.adoc[] include::../common/chapters/gfdl.adoc[] - diff --git a/OsmoTRX/osmotrx-usermanual.adoc b/OsmoTRX/osmotrx-usermanual.adoc index 249a21c..3b2e991 100644 --- a/OsmoTRX/osmotrx-usermanual.adoc +++ b/OsmoTRX/osmotrx-usermanual.adoc @@ -23,6 +23,8 @@ include::chapters/counters.adoc[] include::chapters/configuration.adoc[] +include::../common/chapters/trx_if.adoc[] + include::../common/chapters/port_numbers.adoc[] include::../common/chapters/bibliography.adoc[] diff --git a/common/chapters/trx_if.adoc b/common/chapters/trx_if.adoc new file mode 100644 index 0000000..4fb8f9b --- /dev/null +++ b/common/chapters/trx_if.adoc @@ -0,0 +1,156 @@ +[[trx_if]] +== TRX Manager UDP socket interface + +This is the protocol used between `osmo-trx` and `osmo-bts-trx`. + +Each TRX Manager UDP socket interface represents a single ARFCN. Each of these +per-ARFCN interfaces is a pair of UDP sockets, one for control and one for data. +Given a base port B (5700), the master clock interface is at port P=B. The +TRX-side control interface for C(N) is on port P=B+2N+1 and the data interface +is on an odd numbered port P=B+2N+2. The corresponding core-side interface for +every socket is at P+100. For any given build, the number of ARFCN interfaces +can be fixed. + +=== Indications on the Master Clock Interface + +The master clock interface is output only (from the radio). +Messages are "indications". + +CLOCK gives the current value of the transceiver clock to be used by the core. +This message is sent whenever a trasmission packet arrives that is too late or +too early. The clock value is NOT the current transceiver time. It is a time +setting the the core should use to give better packet arrival times. +---- +IND CLOCK +---- + +=== Commands on the Per-ARFCN Control Interface + +The per-ARFCN control interface uses a command-reponse protocol. Commands are +NULL-terminated ASCII strings, one per UDP socket. Each command has a +corresponding response. + +Every command is of the form: +---- +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 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 +already on, it response with success to this command. +---- +CMD POWERON +RSP POWERON +---- + +`SETPOWER` sets output power in dB wrt full scale. +This command fails if the transmitter and receiver are not running. +---- +CMD SETPOWER +RSP SETPOWER +---- + +`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 +RSP ADJPOWER +---- + +==== 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 +---- + +==== Timeslot Control + +`SETSLOT` sets the format of the uplink timeslots 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 +---- + +=== Messages on the per-ARFCN Data Interface + +Messages on the data interface carry one radio burst per UDP message. + +==== Received Data Burst + +[packetdiag] +---- +{ + colwidth = 32 + node_height = 40 + + 0: T + 1-4: FN + 5: A + 6-7: C + 8-155: Payload +} +---- + +* _T_: timeslot index +* _FN_: GSM frame number, big endian +* _A_: RSSI in -dBm +* _C_: correlator timing offset in 1/256 symbol steps, 2's-comp, big endian +* _Payload_: 148 bytes soft symbol estimates, 0 -> definite "0", 255 -> definite "1" + +==== Transmit Data Burst + +[packetdiag] +---- +{ + colwidth = 32 + node_height = 40 + + 0: T + 1-4: FN + 5: A + 6-153: Payload +} +---- + +* _T_: timeslot index +* _FN_ GSM frame number, big endian +* _A_: transmit level wrt ARFCN max, -dB (attenuation) +* _Payload_: 148 bytes output symbol values, 0 & 1 -- cgit v1.2.3