aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorPau Espin Pedrol <pespin@sysmocom.de>2018-03-06 17:13:13 +0100
committerPau Espin Pedrol <pespin@sysmocom.de>2018-03-06 17:50:28 +0100
commit9af4229dbe5829b00ebd9a06575a55d50a6c0613 (patch)
tree301c1809eb0bdc5d2671056ad0d7bc68bebd7372
parentfe5b55e1c80432a0a50bdd21b605b93a704605bf (diff)
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
-rw-r--r--OsmoBTS/osmobts-usermanual.adoc3
-rw-r--r--OsmoTRX/osmotrx-usermanual.adoc2
-rw-r--r--common/chapters/trx_if.adoc156
3 files changed, 160 insertions, 1 deletions
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 <totalFrames>
+----
+
+=== 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 <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 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 <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
+
+`SETSLOT` sets the format of the uplink timeslots 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>
+----
+
+=== 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