--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README	Thu Aug 29 14:56:30 2024 +0000
@@ -0,0 +1,35 @@
+The hack program in this repository is intended to run on a lab machine (which
+can be RPi etc) that drives an E1 BTS by way of an icE1usb adapter and osmo-e1d.
+
+When a traditional E1 BTS activates a speech or data TCH, it starts transmitting
+TRAU-UL frames on the E1 subslot corresponding to the activated TDMA ts, and it
+expects to receive back TRAU-DL frames shortly thereafter.  If those TRAU-DL
+frames don't appear as expected, the BTS declares remote transcoder failure and
+ends the call attempt - hence a lab test setup has to include a TRAU emulator
+to keep the BTS happy, even if the only objective is to keep the call open and
+capture TRAU-UL output.
+
+The standard solution in Osmocom is to run OsmoMGW in E1 interface mode.
+However, my primary objective was to capture the byte stream coming from the
+TRAU-frame-carrying E1 timeslot and record it into a file for later analysis
+offline - and I found it too difficult to hack this function into OsmoMGW.
+Therefore, I took a different approach:
+
+* Because OsmoBSC still needs its associated OsmoMGW, I do run the latter, but
+  I point it at a fake E1 interface (vpair in osmo-e1d) instead of the real one.
+  (OsmoBSC still talks to the real E1 for OML and RSL.)
+
+* The hack program contained in this repository opens the real timeslot on the
+  real E1 and acts as a fake TRAU, reacting to TRAU-UL output from the BTS and
+  responding with TRAU-DL frames.  This faketrau program also implements the
+  recording function.
+
+The only version currently implemented is faketrau-16k: it opens a single E1 ts
+and treats it as four 16 kbit/s subslots.  It acts like real TRAUs in that it
+needs to receive TRAU-UL frames from the BTS in order to activate a channel,
+and the TRAU-UL frame type in bits C1-C5 indicates the codec type (FR or EFR),
+selecting the type of TRAU-DL frames that need to be sent back to the BTS.
+
+The stream of TRAU-DL frames sent to the BTS by faketrau-16k consists of
+GSM 06.11 silence frames in the case of FRv1 or decoder homing frames in the
+case of EFR.