freecalypso-tools: doc/TCH-bit-access annotate

annotate doc/TCH-bit-access @ 964:a96cb97b66a2

ringtools/imy: fix duplicate definition of tdma_durations[] The bug was reported by Vadim Yanitskiy <fixeria@osmocom.org>, although the present fix is slightly different from the contributed patch: because main.c doesn't need this tdma_durations[] array at all, let's simply remove the reference to this array from main.c rather than turn it into an extern. I no longer remember my original thought flow that resulted (by mistake) in tdma_durations[] being multiply defined in main.c and durations.c. My intent might have been to define all globals in main.c and have the reference in durations.c be an extern - and I missed that extern - but without clear memory, I have no certainty. In any case, having this data array defined in the same module that fills it (durations.c) is sensible, so let's make it the new way.

author	Mychaela Falconia <falcon@freecalypso.org>
date	Thu, 31 Aug 2023 19:38:18 +0000
parents	1f2459a776d7
children

rev	line source
8 2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	1 It has been discovered that the DSP ROM in the Calypso GSM baseband processor
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	2 implements one nifty feature which is not used at all in standard phone or modem
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	3 operation, but which can be used for all kinds of interesting hacks: the traffic
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	4 channel (TCH) bits coming out of the GSM 05.03 channel decoder in the downlink
907 3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	5 direction (to be fed to the channel mode-appropriate speech decoder) can be read
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	6 out of the DSP's API RAM in real time, and in the uplink direction the user can
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	7 feed her own bits to the input of the GSM 05.03 channel encoder, effectively
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	8 suppressing the output of the internal vocoder.
8 2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	9
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	10 The DSP mechanism in question is known to work in TCH/FS and TCH/EFS channel
907 3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	11 modes, corresponding to FR1 and EFR codecs; it also appears to work for TCH/HS
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	12 (HR1 codec), but we (FreeCalypso) haven't tested it because almost no one uses
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	13 that infamous HR1 codec - the commercial GSM network in our part of the world
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	14 gives you a full-rate channel if your phone does not support AMR. It would be
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	15 possible to implement HR1 in our own test GSM network, but the effort that would
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	16 be required is difficult to justify. Exploring TCH tap modes with AMR or CSD
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	17 traffic channels is likewise a subject for further study.
8 2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	18
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	19 In order to make use of this TCH bit access feature, one needs 3 things:
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	20
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	21 1) Firmware on the Calypso (the ARM part) that reads downlink bits from the DSP
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	22 and writes uplink bits into it while doing everything else that a GSM fw must
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	23 do in order to operate the MS;
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	24
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	25 2) Some protocol for passing these TCH bits into and out of the Calypso device;
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	26
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	27 3) A source for TCH UL bits and a sink for TCH DL bits on the external host.
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	28
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	29 In the case of FreeCalypso, we have defined our own protocol for passing TCH
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	30 bits into and out of Calypso GSM devices running one of our firmwares in the
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	31 form of an extension to TI's RVTMUX interface, i.e., we have defined a new
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	32 RVTMUX channel for this TCH interface and defined the packet types and formats
907 3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	33 to be sent over the wire. On the Calypso side the special functionality in
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	34 question was originally implemented in FC Citrine firmware in 2016 and then set
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	35 aside for some years; when the right time came to resurrect this feature in late
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	36 2022, it turned out that the original implementation from 2016 was slightly
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	37 incorrect, and the new implementation in FC Tourmaline fw is slightly different.
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	38 On the host tools side the RVTMUX-based TCH interface is supported in rvinterf
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	39 and fc-shell; the new version as of fc-host-tools-r18 supports both 2016 and
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	40 2022 versions of this over-the-wire interface.
8 2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	41
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	42 The TCH bit access mechanism in FreeCalypso has been designed with an objective
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	43 of presenting to the user exactly what TI's DSP presents to us, i.e., standing
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	44 out of the way as much as possible. TI's DSP presents TCH downlink bits and
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	45 accepts TCH uplink bits in the form of an array of 16-bit words; the bit order
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	46 within these words corresponds to the GSM 05.03 channel encoder bit order (with
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	47 a couple of TI-specific quirks documented below) and NOT that of the GSM 06.10
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	48 or EFR codecs. On the RVTMUX serial interface between the Calypso device and
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	49 the external host we transfer each TCH frame as a block of 33 bytes; our Calypso
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	50 firmwares translate between these bytes and the DSP's 16-bit words, but do not
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	51 reorder or change the bits in any way.
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	52
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	53 On the host tools side our fc-shell utility provides user commands to save TCH
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	54 DL bits into a file and to play TCH UL bits from a file; in the present version
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	55 these files are written and read in an ASCII-based hex format. In these ASCII
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	56 files each TCH frame is represented as a string of 66 hexadecimal digits, and
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	57 these hex digits correspond directly to the 33 bytes being read out of or
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	58 written into DSP API words. Therefore, in order to generate and/or interpret
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	59 these hexadecimal strings correctly, you (the user) need to understand the bit
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	60 order and mapping used by TI's implementation of the GSM 05.03 channel encoder.
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	61
907 3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	62 As of late 2022, there is a new TCH-tap-modes article in our freecalypso-docs
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	63 repository that covers in detail the format of TI's DSP buffers for TCH DL and
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	64 UL bits, as well as all known information about TCH DL status words and bit
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	65 flags. But here is our original description from 2016:
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	66
8 2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	67 Recall from the GSM specs that the 260 bits which comprise one speech frame are
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	68 not all treated equally, instead they are divided into 182 class 1 bits which
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	69 are protected by a convolutional encoder and 78 class 2 bits which are
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	70 transmitted without any forward error correction. Furthermore, the first 50 of
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	71 the class 1 bits are also protected by a CRC. The order in which the bits
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	72 appear on TI's DSP interface corresponds to this division, known as the order of
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	73 subjective importance.
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	74
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	75 Now let's look at the actual bit order and mapping which you need to understand
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	76 in order to make sense of the hex strings in tch record and tch play files.
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	77 The bit numbering is from the most significant bit to the least significant bit,
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	78 i.e., in our string of 66 hex digits the most significant bit of the leftmost
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	79 digit is bit 0 and the least significant bit of the rightmost digit is bit 263.
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	80 TI's DSP assigns these bits as follows:
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	81
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	82 * Bits 0 through 181 correspond to the 182 protected (class 1) bits in the
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	83 standard GSM 05.03 order;
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	84
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	85 * Bits 182 through 185 are unused - put zeros there if you are generating them
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	86 yourself;
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	87
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	88 * Bits 186 through 263 correspond to the 78 unprotected (class 2) bits in the
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	89 standard GSM 05.03 order.
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	90
907 3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	91 TCH DL recording
8 2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	92 ================
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	93
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	94 When you are in an established voice call in fc-shell, you can record the
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	95 downlink TCH bits as follows:
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	96
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	97 tch record <name of file to put the recording into>
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	98
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	99 If you would like to record an entire call from the beginning, issue the
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	100 tch record command as above before the ATD or ATA command that dials or answers
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	101 the call. Either way, whether you are recording a call from the beginning or
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	102 from the middle, you need to eventually stop your recording with this command:
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	103
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	104 tch record stop
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	105
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	106 You can issue this stop command before or after the call is terminated, but
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	107 until you issue this tch record stop command, the output file is not closed and
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	108 thus may not be written to the file system.
2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	109
907 3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	110 The recording is written in an ASCII line-based format with one line for every
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	111 received TCH DL frame, but the exact format of each written line will depend on
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	112 which firmware version is in use. If you are running ancient Citrine firmware
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	113 that emits its TCH DL output in the old format from 2016 (now known to be
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	114 incomplete and thus unusable for proper decoding), fc-shell will likewise write
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	115 its ASCII output in the old format, which won't be covered further as it is
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	116 deprecated and not practically useful. However, if you are running current
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	117 FreeCalypso firmware with the resurrected (late 2022) version of the TCH tap
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	118 feature, each TCH DL frame will be sent by the fw and received by fc-shell in
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	119 the new over-the-wire format, and fc-shell will write the recording file in the
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	120 new ASCII format documented in the TCH-tap-modes article in freecalypso-docs.
8 2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	121
907 3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	122 Once you have captured a TCH DL recording, what can you do with it? If the
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	123 recording came from an FR1 call, you will need to pass it through an Rx DTX
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	124 handler for FR1 (see GSM 06.11, 06.12 and 06.31 specs) before you can pass it
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	125 to a naive GSM 06.10 decoder such as classic Unix libgsm, and if the recording
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	126 came from an EFR call, you will need to pass it to a proper EFR (not AMR!)
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	127 decoder that includes the necessary EFR Rx DTX handler. Neither of the two
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	128 just-mentioned library pieces (neither the Rx DTX handler for FR1 nor a proper,
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	129 not-same-as-AMR implementation of GSM EFR) could be found among the existing
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	130 body of FOSS as of 2022, thus we (FreeCalypso and Themyscira Wireless)
947 1f2459a776d7 doc/TCH-bit-access: point to gsm-codec-lib release tarball URL Mychaela Falconia <falcon@freecalypso.org> parents: 946 diff changeset	131 implemented our own. Please look in our GSM codec libraries & utilities
1f2459a776d7 doc/TCH-bit-access: point to gsm-codec-lib release tarball URL Mychaela Falconia <falcon@freecalypso.org> parents: 946 diff changeset	132 package:
1f2459a776d7 doc/TCH-bit-access: point to gsm-codec-lib release tarball URL Mychaela Falconia <falcon@freecalypso.org> parents: 946 diff changeset	133
1f2459a776d7 doc/TCH-bit-access: point to gsm-codec-lib release tarball URL Mychaela Falconia <falcon@freecalypso.org> parents: 946 diff changeset	134 ftp://ftp.freecalypso.org/pub/GSM/codecs/gsm-codec-lib-latest.tar.bz2
8 2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	135
907 3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	136 Inside our gsm-codec-lib package you will find gsmfr-dlcap-* and gsmefr-dlcap-*
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	137 utilities that read TCH downlink capture files written by fc-shell tch record
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	138 and perform various decoding operations - please refer to further documentation
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	139 within that package.
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	140
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	141 Please don't use the old fc-tch2fr utility - the function it performs is now
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	142 known to be a bogo-transform, and it can't grok the new TCH DL recording format
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	143 which you will get with current FreeCalypso fw.
8 2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	144
907 3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	145 TCH UL play
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	146 ===========
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	147
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	148 The uplink sending mechanism can be exercised as follows:
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	149
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	150 1. If you are going to be in an FR1 call, prepare a speech sample in the GSM
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	151 06.10 codec format using any Unix/Linux audio tool that can write the de
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	152 facto standard libgsm format. For example, using SoX:
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	153
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	154 rec -c1 recording.gsm
8 2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	155
907 3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	156 SoX will write the recording in the GSM 06.10 libgsm format based on the
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	157 .gsm suffix at the end of the recording file name; the -c1 option is needed
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	158 to disable stereo, otherwise the recording will be slowed down 2x.
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	159 Alternatively, you can use our new gsmfr-encode utility (gsm-codec-lib
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	160 package) to encode from WAV into GSM 06.10, or gsmfr-encode-r for raw BE
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	161 input instead of WAV.
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	162
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	163 OTOH, if you are going to be in an EFR call rather than FR1, you will need to
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	164 prepare a speech sample in the EFR codec format instead. You will need to
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	165 use Themyscira gsmefr-encode or gsmefr-encode-r utilities, or convert from
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	166 AMR (MR122 mode only, no DTX) with our gsm-amr2efr utility.
8 2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	167
907 3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	168 2. Convert your speech sample from libgsm standard format (FR1) or Themyscira
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	169 gsmx format (EFR) into our ad hoc hex strings for playing into a TCH uplink:
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	170
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	171 fc-fr2tch recording.gsm recording.tch-ul
8 2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	172
907 3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	173 or
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	174
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	175 fc-efr2tch recording.gsmx recording.tch-ul
8 2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	176
907 3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	177 3. In fc-shell, when you are in an established voice call, issue this command:
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	178
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	179 tch play recording.tch-ul
8 2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	180
907 3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	181 You should now hear the speech sample you recorded in step 1 above on the other
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	182 end of the GSM call. Needless to say, the TCH mode of the call (TCH/FS or
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	183 TCH/EFS) needs to match the codec in which your to-be-played recording was
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	184 prepared, otherwise the other end of the call will receive garbage!
8 2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	185
907 3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	186 Controlling the selection of speech codec for calls
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	187 ===================================================
8 2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	188
907 3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	189 One very obvious shortcoming of the present facilities for voice TCH redirection
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	190 is that we only support FR1 and EFR codecs, but not AMR. However, most GSM
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	191 networks prefer to use AMR when the MS supports it - and in regular operation
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	192 with a speaker & mic user connection (as opposed to TCH tap modes), our current
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	193 FreeCalypso firmwares do support AMR when running on Calypso C035 silicon with
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	194 DSP ROM version 3606. (DSP ROM version 3416 together with the respective patch
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	195 version also appears to have working AMR, at least in light testing, although
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	196 of course we do NOT recommend it for production use.) Therefore, if you wish
946 8f7c50e1fa3b doc/TCH-bit-access: refer to Speech-codec-selection in freecalypso-docs Mychaela Falconia <falcon@freecalypso.org> parents: 907 diff changeset	197 to play with EFR, you need to tell the network (via the Bearer capability
907 3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	198 information element in CC messages) that your MS does not support AMR, and if
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	199 you wish to play with FR1, you need to tell the network that your MS only
3de3b34189be doc/TCH-bit-access: update for newly resurrected version Mychaela Falconia <falcon@freecalypso.org> parents: 8 diff changeset	200 supports FR1 and no others.
8 2748f257312b doc/TCH-bit-access: new write-up Mychaela Falconia <falcon@freecalypso.org> parents: diff changeset	201
946 8f7c50e1fa3b doc/TCH-bit-access: refer to Speech-codec-selection in freecalypso-docs Mychaela Falconia <falcon@freecalypso.org> parents: 907 diff changeset	202 Please refer to Speech-codec-selection article in freecalypso-docs for more
8f7c50e1fa3b doc/TCH-bit-access: refer to Speech-codec-selection in freecalypso-docs Mychaela Falconia <falcon@freecalypso.org> parents: 907 diff changeset	203 information and specific instructions.

FreeCalypso > hg > freecalypso-tools

annotate doc/TCH-bit-access @ 964:a96cb97b66a2