FreeCalypso > hg > freecalypso-tools

annotate doc/TCH-bit-access @ 929:ab771ce34fac

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
rvinterf/lowlevel/format.c: get rid of static fmtbuf
author Mychaela Falconia <falcon@freecalypso.org>
date Tue, 23 May 2023 05:56:08 +0000
parents 3de3b34189be
children 8f7c50e1fa3b
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)
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
131 implemented our own. Please look for our GSM codec libraries & utilities
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
132 package, which is expected to reach its first official release some time in
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
133 early 2023.
8
2748f257312b doc/TCH-bit-access: new write-up
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
134
907
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
135 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
136 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
137 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
138 within that package.
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
139
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
140 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
141 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
142 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
143
907
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
144 TCH UL play
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
145 ===========
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 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
148
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
149 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
150 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
151 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
152
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
153 rec -c1 recording.gsm
8
2748f257312b doc/TCH-bit-access: new write-up
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
154
907
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
155 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
156 .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
157 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
158 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
159 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
160 input instead of WAV.
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
161
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
162 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
163 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
164 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
165 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
166
907
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
167 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
168 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
169
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
170 fc-fr2tch recording.gsm recording.tch-ul
8
2748f257312b doc/TCH-bit-access: new write-up
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
171
907
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
172 or
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
173
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
174 fc-efr2tch recording.gsmx recording.tch-ul
8
2748f257312b doc/TCH-bit-access: new write-up
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
175
907
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
176 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
177
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
178 tch play recording.tch-ul
8
2748f257312b doc/TCH-bit-access: new write-up
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
179
907
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
180 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
181 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
182 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
183 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
184
907
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
185 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
186 ===================================================
8
2748f257312b doc/TCH-bit-access: new write-up
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
187
907
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
188 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
189 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
190 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
191 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
192 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
193 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
194 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
195 of course we do NOT recommend it for production use.) Therefore, if you wish
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
196 to play with EFR, you need to tell the network (via the Bearer Capabilities
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
197 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
198 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
199 supports FR1 and no others.
8
2748f257312b doc/TCH-bit-access: new write-up
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
200
907
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
201 The outstanding issue here is that we need to implement some mechanism in our
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
202 FreeCalypso firmwares, probably a custom AT command, that will modify the
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
203 Bearer Capabilities IE (artificially restrict the set of supported codecs) on a
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
204 per-call basis. Until we implement the necessary support, the only current way
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
205 to create such codec-restricted operation is by writing a /pcm/MSCAP file into
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
206 FFS with the desired bit mask of supported codecs - but this method is hugely
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
207 inconvenient because this file is read only on fw boot, thus every modification
3de3b34189be doc/TCH-bit-access: update for newly resurrected version
Mychaela Falconia <falcon@freecalypso.org>
parents: 8
diff changeset
208 requires a full reboot cycle.