Checking in a more relevant README.
This READMY is from the OpenBTS's TRXManager and actually describes the transceiver
API and behavior.
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.
-
-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.
-
-
-These are the directories:
-
-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
+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.
-By default, OpenBTS assumes the following UDP port assignments:
+Indications on the Master Clock 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 master clock interface is output only (from the radio).
+Messages are "indications".
-These can be controlled in the CONFIG table in /etc/OpenBTS.db.
-
-Standrd paths:
-/OpenBTS -- Binary installation.
-/etc/OpenBTS -- Configuration databases.
-/var/run/OpenBTS -- Real-time reporting databases.
-
-The script apps/setUpFiles.sh will create these directories and install the
-correct files in them.
+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
-Release history:
+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:
-Release Name SVN Reposiory SVN Rev Comments
+CMD <cmdtype> [params]
-1.0 (none) SF.net ?? completed L1, L2
+The <cmdtype> is the actual command.
+Parameters are optional depending on the commands type.
+Every response is of the form:
-1.1 Arnaudville GNU Radio r10019 (trunk)
+RSP <cmdtype> <status> [result]
-1.2 Breaux Bridge GNU Radio r10088 (trunk) GNU Build, very early assignment
-
-1.3 Carencro KSP r1 (trunk) first post-injunction release
-
-1.4 Donaldsonville KSP r23 (trunk) fixed Ubuntu build error
-
-1.5 Eunice KSP r39 (trunk) fixed L2 bugs related to segmentation
- removed incomplete SMS directory
- moved "abort" calls into L3 subclasses
-
-1.6 New Iberia KSP r130 (trunk) import of all 2.2 improvements to non-SMS release
+The <status> is 0 for success and a non-zero error code for failure.
+Successful responses may include results, depending on the command type.
-2.0 St. Francisville KSP r54 (smswork) SMS support
- file-based configuration
+Power Control
-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
+POWEROFF shuts off transmitter power and stops the demodulator.
+CMD POWEROFF
+RSP POWEROFF <status>
-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
+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 <status>
-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
+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>
-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
+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>
-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
+Tuning Control
-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
+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 <kHz>
+RSP RXTUNE <status> <kHz>
-2.5.1 Lacassine KSP r595 fixed some build bugs for some Linux distros
+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 <kHz>
+RSP TXTUNE <status> <kHz>
-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)
+Timeslot Control
-2.5.4 Lacassine KSP r812 merged fixes to build under latest Fedora and
- to build with git GnuRadio (r814)
+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>
-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)
+Messages on the per-ARFCN Data Interface
-2.8 Opelousas Range rxxx move databases to /etc and /var
- RRLP aiding support
+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
+
+