[MERGED] osmo-gsm-manuals[master]: Introduce chapter trx_if.adoc and add it to OsmoTRX and OsmoBTS

This is merely a historical archive of years 2008-2021, before the migration to mailman3.

A maintained and still updated list archive can be found at https://lists.osmocom.org/hyperkitty/list/gerrit-log@lists.osmocom.org/.

Harald Welte gerrit-no-reply at lists.osmocom.org
Tue Mar 6 19:42:07 UTC 2018 

Harald Welte has submitted this change and it was merged.

Change subject: Introduce chapter trx_if.adoc and add it to OsmoTRX and OsmoBTS
......................................................................


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
---
M OsmoBTS/osmobts-usermanual.adoc
M OsmoTRX/osmotrx-usermanual.adoc
A common/chapters/trx_if.adoc
3 files changed, 160 insertions(+), 1 deletion(-)

Approvals:
  Harald Welte: Looks good to me, approved
  Jenkins Builder: Verified



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

-- 
To view, visit https://gerrit.osmocom.org/7140
To unsubscribe, visit https://gerrit.osmocom.org/settings

Gerrit-MessageType: merged
Gerrit-Change-Id: I56c418eef0f826ae1aadbed5b151fbed241c7885
Gerrit-PatchSet: 2
Gerrit-Project: osmo-gsm-manuals
Gerrit-Branch: master
Gerrit-Owner: Pau Espin Pedrol <pespin at sysmocom.de>
Gerrit-Reviewer: Harald Welte <laforge at gnumonks.org>
Gerrit-Reviewer: Jenkins Builder

More information about the gerrit-log mailing list