From 2beb1adcead95339271376216e685755f00c1594 Mon Sep 17 00:00:00 2001 From: Alexander Chemeris Date: Mon, 8 Jun 2015 23:44:58 -0400 Subject: Checking in a more relevant README. This READMY is from the OpenBTS's TRXManager and actually describes the transceiver API and behavior. --- README | 218 +++++++++++++++++++++++++---------------------------------------- 1 file changed, 83 insertions(+), 135 deletions(-) (limited to 'README') diff --git a/README b/README index 3678c62..502d661 100644 --- a/README +++ b/README @@ -1,168 +1,116 @@ -Welcome to the OpenBTS source code. +This is the interface to the transcevier. +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. +Give 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. -For free support, please subscribe to openbts-discuss@lists.sourceforge.net. -See http://sourceforge.net/mailarchive/forum.php?forum_name=openbts-discuss -and https://lists.sourceforge.net/lists/listinfo/openbts-discuss for details. -For additional information, refer to http://openbts.org. +Indications on the Master Clock Interface -These are the directories: +The master clock interface is output only (from the radio). +Messages are "indications". -AsteriskConfig Asterisk configuration files for use with OpenBTS. -CommonLib Common-use libraries, mostly C++ wrappers for basic facilities. -Control Control-layer functions for the protocols of GSM 04.08 and SIP. -GSM The GSM stack. -SIP Components of the SIP state machines ued by the control layer. -SMS The SMS stack. -SR The subscriber registry. -TRXManager The interface between the GSM stack and the radio. -Transceiver The software transceiver and specific installation tests. -apps OpenBTS application binaries. -doc Project documentation. -tests Test fixtures for subsets of OpenBTS components. -smqueue RFC-3428 store-and-forward server for SMS +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 -By default, OpenBTS assumes the following UDP port assignments: +Commands on the Per-ARFCN Control Interface -5060 -- Asterisk SIP interface -5061 -- local SIP softphone -5062 -- OpenBTS SIP interface -5063 -- smqueue SIP interface -5064 -- subscriber registry SIP interface -5700-range -- OpenBTS-transceiver 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: -These can be controlled in the CONFIG table in /etc/OpenBTS.db. +CMD [params] -Standrd paths: -/OpenBTS -- Binary installation. -/etc/OpenBTS -- Configuration databases. -/var/run/OpenBTS -- Real-time reporting databases. +The is the actual command. +Parameters are optional depending on the commands type. +Every response is of the form: -The script apps/setUpFiles.sh will create these directories and install the -correct files in them. +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 -Release history: +POWEROFF shuts off transmitter power and stops the demodulator. +CMD POWEROFF +RSP POWEROFF -Release Name SVN Reposiory SVN Rev Comments +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 runnng. +If the transceiver is already on, it response with success to this command. +CMD POWERON +RSP POWERON -1.0 (none) SF.net ?? completed L1, L2 +SETPOWER sets output power in dB wrt full scale. +This command fails if the transmitter and receiver are not running. +CMD SETPOWER +RSP SETPOWER -1.1 Arnaudville GNU Radio r10019 (trunk) +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 -1.2 Breaux Bridge GNU Radio r10088 (trunk) GNU Build, very early assignment -1.3 Carencro KSP r1 (trunk) first post-injunction release +Tuning Control -1.4 Donaldsonville KSP r23 (trunk) fixed Ubuntu build error +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 runnng. +CMD RXTUNE +RSP RXTUNE -1.5 Eunice KSP r39 (trunk) fixed L2 bugs related to segmentation - removed incomplete SMS directory - moved "abort" calls into L3 subclasses +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 runnng. +CMD TXTUNE +RSP TXTUNE -1.6 New Iberia KSP r130 (trunk) import of all 2.2 improvements to non-SMS release +Timeslot Control -2.0 St. Francisville KSP r54 (smswork) SMS support - file-based configuration +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 -2.1 Grand Coteau KSP r70 (smswork) DTMF support - fixed more Linux-related build errors - -lpthread - TLMessage constructor - expanded stack to prevent overflows in Linux - moved gSIPInterface to main app - fixed iterator bug in Pager -2.2 Houma KSP r122 (smswork) added LEGAL notice - removed Assert classes - stop paging on page response - fixed Pager-spin bug - fixed Transceiver spin bugs - fixed 2^32 microsecond rollover bug - reduced stack footprints in Transceiver - fixed SMS timestamps - check LAI before using TMSI in LUR - reduced memory requirement by 75% - removed PagerTest - fixed stale-transaction bug in paging handler - fixed USRP clock rollover bug - faster call connection - new USRPDevice design +Messages on the per-ARFCN Data Interface + +Messages on the data interface carry one radio burst per UDP message. + + +Received Data Burst + +1 byte timeslot index +4 bytes GSM frame number, big endian +1 byte RSSI in -dBm +2 bytes correlator timing offset in 1/256 symbol steps, 2's-comp, big endian +148 bytes soft symbol estimates, 0 -> definite "0", 255 -> definite "1" + + +Transmit Data Burst + +1 byte timeslot index +4 bytes GSM frame number, big endian +1 byte transmit level wrt ARFCN max, -dB (attenuation) +148 bytes output symbol values, 0 & 1 -2.3 Jean Lafitte KSP r190? (trunk) check for out-of-date RACH bursts - better TRX-GSM clock sync - formal logging system - command line interface - emergency call setup - -2.4 Kinder KSP r208? (trunk) fixed BCCH neighbor list bug - support for neighbor lists - fixed support for non-local Asterisk servers - cleaner configuration management - more realtime control of BCCH parameters - proper rejection of Hold messages - fixed L3 hanging bug in MTDCheckBYE - -2.4.1 Kinder KSP r462 fixed lots of valgrind errors - -2.4.2 Kinder KSP r482 zero-length calling party number bug - g++ 4.4 #includes - -2.5 Lacassine KSP r551 imported Joshua Lackey patches - SIP fixes from Anne Kwong - SIP fixes from testing with SMS server - L3 TI handling fixes - SMS server support - GNU Radio 3.2 compatibility - configurable max range and LU-reject cause - "page" & "testcall" CLI features -2.5.1 Lacassine KSP r595 fixed some build bugs for some Linux distros - -2.5.2 Lacassine KSP r630 fixed channel assignment bug for Nokia DCT4+ handsets - -2.5.3 Lacassine KSP r756 merged fix for transceiver startup crash - due to use of uninitialized variables (r646) - merged fix for fusb bug from trunk (r582) - -2.5.4 Lacassine KSP r812 merged fixes to build under latest Fedora and - to build with git GnuRadio (r814) - -2.6 Mamou KSP r886 fixed infamous fusb bug (r582) - fixed idle-filling table size bug - smoother uplink power control - load-limiting downlink power control - new "config" features (optional, static) - IMEI interrogation - fixed MOD "missing FIFO" bug - configurable short code features - fixed transceiver startup crash (r646) - readline support is back - fixed timing advance bug (r844) - added CLI "chans" command - track time-of-use in TMSI table (r844) - added CLI "noise" command (r844) - added CLI "rxpower" command (r844) - added CLI "unconfig" command - -2.7 Natchitoches Range rxxx (never released publicly) - converted TMSITable to sqlite3 (r902) - sqlite3-based configuration (r???) - converted Logger to syslogd (r903) - added support for rest octets (r1022) - external database for transaction reporting (r1184) - external database for channel status reporting (r1203) - in-call delivery and submission of text messages (r1231) - RFC-2833 DMTF (r1249) - -2.8 Opelousas Range rxxx move databases to /etc and /var - RRLP aiding support -- cgit v1.2.3