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
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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.