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 <pes...@sysmocom.de> Gerrit-Reviewer: Harald Welte <lafo...@gnumonks.org> Gerrit-Reviewer: Jenkins Builder