FreeCalypso > hg > gsm-codec-lib

annotate doc/Calypso-TCH-downlink @ 488:6724fbb01a09 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
PACKAGING: grammar fix
author Mychaela Falconia <falcon@freecalypso.org>
date Mon, 20 May 2024 22:02:36 +0000
parents 5e2d849a4fbc
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
168
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
1 It has been discovered that the implementation of standard signal processing
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
2 chains for speech TCH downlink and uplink in the DSP ROM in the Calypso GSM
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
3 baseband processor allows these signal processing chains to be tapped at certain
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
4 points, as detailed in the TCH-tap-modes article in our freecalypso-docs Hg
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
5 repository. There is a mechanism to capture the stream of received traffic
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
6 frames on TCH DL, and there is another mechanism by which an externally supplied
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
7 stream can be "played" into TCH UL.
136
8eb0e7a39409 doc: document command line utilities
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8
8eb0e7a39409 doc: document command line utilities
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 I (Mother Mychaela) previously played with this functionality back in 2016, and
182
2254fa16ec5f doc/Calypso-TCH-downlink: update for fc-host-tools-r18 release
Mychaela Falconia <falcon@freecalypso.org>
parents: 180
diff changeset
10 it's been mostly shelved since then. This functionality became interesting
2254fa16ec5f doc/Calypso-TCH-downlink: update for fc-host-tools-r18 release
Mychaela Falconia <falcon@freecalypso.org>
parents: 180
diff changeset
11 once again in late 2022: now that we have a proper set of codec libraries (the
136
8eb0e7a39409 doc: document command line utilities
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 present package) and a proper understanding of Rx DTX handling requirements, we
8eb0e7a39409 doc: document command line utilities
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 can take another shot at decoding TCH downlink captures taken from Calypso GSM
8eb0e7a39409 doc: document command line utilities
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 MS.
8eb0e7a39409 doc: document command line utilities
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15
168
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
16 The overall functionality is described in the TCH-tap-modes article in
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
17 freecalypso-docs; the mechanism for capturing TCH DL bits from Calypso DSP is
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
18 split between FreeCalypso GSM MS firmware (added to FC Tourmaline as of
182
2254fa16ec5f doc/Calypso-TCH-downlink: update for fc-host-tools-r18 release
Mychaela Falconia <falcon@freecalypso.org>
parents: 180
diff changeset
19 2022-12-13) and the fc-shell utility in the FC host tools package, updated as
2254fa16ec5f doc/Calypso-TCH-downlink: update for fc-host-tools-r18 release
Mychaela Falconia <falcon@freecalypso.org>
parents: 180
diff changeset
20 of fc-host-tools-r18 to support the new FreeCalypso fw. There is also a set of
2254fa16ec5f doc/Calypso-TCH-downlink: update for fc-host-tools-r18 release
Mychaela Falconia <falcon@freecalypso.org>
parents: 180
diff changeset
21 utilities included in the present GSM codec libraries & utilities package for
2254fa16ec5f doc/Calypso-TCH-downlink: update for fc-host-tools-r18 release
Mychaela Falconia <falcon@freecalypso.org>
parents: 180
diff changeset
22 parsing and decoding these Calypso TCH DL captures; the present document
2254fa16ec5f doc/Calypso-TCH-downlink: update for fc-host-tools-r18 release
Mychaela Falconia <falcon@freecalypso.org>
parents: 180
diff changeset
23 describes these utilities.
168
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
24
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
25 As explained in the TCH-tap-modes article in freecalypso-docs, the mechanism
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
26 for capturing TCH DL is currently implemented for TCH/FS, TCH/HS and TCH/EFS,
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
27 corresponding to FR1, HR1 and EFR codecs. However, further parsing and decoding
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
28 support has only been implemented for FR1 and EFR codecs in the present package,
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
29 in the form of the following utilities:
136
8eb0e7a39409 doc: document command line utilities
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30
168
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
31 gsmfr-dlcap-parse This program reads a TCH/FS DL capture file and parses
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
32 it for human analysis. All input fields are passed
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
33 through to the output, but the program also computes
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
34 the ternary SID flag of GSM 06.31 section 6.1.1 from
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
35 the payload bits (for comparison against what the DSP
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
36 wrote in its status word 0) and prints all broken-down
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
37 parameter fields of each GSM 06.10 FR1 codec frame.
136
8eb0e7a39409 doc: document command line utilities
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38
168
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
39 gsmfr-dlcap-gsmx This program reads a TCH/FS DL capture file and converts
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
40 it into an extended-libgsm (gsmx) file containing a mix
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
41 of FR1 codec frames and Themyscira BFI markers. The
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
42 latter BFI markers will be emitted in those frame
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
43 positions where FACCH was received instead of speech,
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
44 or where the DSP otherwise indicated BFI=1. The gsmx
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
45 output from this utility needs to be fed to gsmfr-decode
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
46 from the present package, so that our FR1 Rx DTX
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
47 preprocessor will take care of SIDs and BFIs, completing
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
48 the required GSM MS processing chain for TCH/FS DL.
136
8eb0e7a39409 doc: document command line utilities
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49
168
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
50 gsmefr-dlcap-parse This program reads a TCH/EFS DL capture file and parses
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
51 it for human analysis. All input fields are passed
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
52 through to the output, but the program also computes
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
53 the ternary SID flag of GSM 06.81 section 6.1.1 from
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
54 the payload bits (for comparison against what the DSP
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
55 wrote in its status word 0) and prints all broken-down
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
56 parameter fields of each EFR codec frame. Finally, each
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
57 triplicated bit group of GSM 05.03 section 3.1.1.2 is
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
58 printed as an octal digit, to aid human analysis of how
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
59 the DSP writes these bits in its a_dd_0 buffer.
136
8eb0e7a39409 doc: document command line utilities
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60
168
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
61 gsmefr-dlcap-gsmx This program reads a TCH/EFS DL capture file and
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
62 converts it into a gsmx binary file, containing a mix
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
63 of EFR codec frames and Themyscira BFI markers. The
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
64 latter BFI markers will be emitted in those frame
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
65 positions where FACCH was received instead of speech,
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
66 or where the DSP otherwise indicated BFI=1. The gsmx
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
67 output from this utility needs to be fed to
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
68 gsmefr-decode (or gsmefr-decode-r) from the present
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
69 package.
136
8eb0e7a39409 doc: document command line utilities
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70
168
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
71 gsmefr-dlcap-dec This program reads a TCH/EFS DL capture file and feeds
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
72 it directly to the EFR reference decoder implemented in
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
73 libgsmefr, without going through a gsmx intermediary.
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
74
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
75 Additional notes:
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
76
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
77 * The new gsmfr-dlcap-gsmx utility described above replaces the old fc-tch2fr
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
78 utility from FC host tools - the latter should now be considered a bogon.
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
79 The required GSM MS processing chain for TCH/FS DL includes the step of Rx
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
80 DTX handler between the output of GSM 05.03 channel decoder and the input of
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
81 GSM 06.10 speech decoder; the old chain of fc-tch2fr followed by libgsm
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
82 decoding omitted this critical step and thus produced very unkind-on-ears
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
83 sounds.
136
8eb0e7a39409 doc: document command line utilities
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84
168
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
85 * gsmefr-dlcap-dec has been written as a bold attempt to replicate the complete
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
86 Rx DTX handler and speech decoder (the part of TCH DL processing chain that
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
87 sits past the a_dd_0 buffer) as they are implemented inside TI's DSP. Such a
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
88 feat won't be possible for FR1 codec (other than by a Herculean effort of full
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
89 static reversing of the DSP ROM) because there is no bit-exact definition of
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
90 FR1 Rx DTX functions in GSM specs, but for EFR there is a bit-exact reference
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
91 implementation from ETSI. *If* TI's DSP matches this bit-exact reference
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
92 (there are some aspects of Rx DTX handling where this bit-exact reference is
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
93 considered to be an example rather than normative, see GSM 06.61), then there
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
94 is a chance we could replicate TI's DSP chain externally - but only if we can
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
95 figure out exactly how the bits of a_dd_0[0] drive the logic of their Rx DTX
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
96 handler. The Mother's plan is to capture the DSP's decoded speech output from
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
97 MCSI on an FCDEV3B using a small FPGA board with a PCM-to-UART logic function,
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
98 while simultaneously capturing TCH DL bits in the a_dd_0 buffer, then run
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
99 gsmefr-dlcap-dec on the captured TCH DL booty and see if we can replicate the
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
100 DSP's end output - but until then, this gsmefr-dlcap-dec program should be
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
101 treated as an unfinished experiment in progress.
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
102
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
103 * In the case of FR1 codec, there is no prescribed bit-exact definition for the
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
104 Rx DTX handler (GSM 06.11, 06.12 and 06.31 specs define general requirements,
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
105 but aren't bit-exact in most aspects), and the way in which we (Themyscira
304
03b0702f4463 doc/Calypso-TCH-downlink: s/libgsmfrp/libgsmfr2/
Mychaela Falconia <falcon@freecalypso.org>
parents: 182
diff changeset
106 Wireless) have implemented our FR1 Rx DTX handler (libgsmfr2 in the present
168
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
107 package) perfectly matches our gsmx binary file format for good vs bad frames.
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
108 Therefore, in the case of FR1 codec there is nothing to be gained by skipping
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
109 gsmx and calling library functions directly, and thus there is no FR1
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
110 counterpart to gsmefr-dlcap-dec - just use gsmfr-dlcap-gsmx followed by
486e19acc66f doc/Calypso-TCH-downlink: document new utilities
Mychaela Falconia <falcon@freecalypso.org>
parents: 136
diff changeset
111 gsmfr-decode or gsmfr-decode-r.
180
62c0359ff2a8 doc/Calypso-TCH-downlink: document use of tools on voice memos
Mychaela Falconia <falcon@freecalypso.org>
parents: 168
diff changeset
112
62c0359ff2a8 doc/Calypso-TCH-downlink: document use of tools on voice memos
Mychaela Falconia <falcon@freecalypso.org>
parents: 168
diff changeset
113 * In addition to TCH DL capture files, gsmfr-dlcap-parse also accepts the hex
62c0359ff2a8 doc/Calypso-TCH-downlink: document use of tools on voice memos
Mychaela Falconia <falcon@freecalypso.org>
parents: 168
diff changeset
114 output from fc-vm2hex, originating from TCS211 voice memo recordings,
62c0359ff2a8 doc/Calypso-TCH-downlink: document use of tools on voice memos
Mychaela Falconia <falcon@freecalypso.org>
parents: 168
diff changeset
115 including fc-vm2hex output in the case of VM recordings made in DTX mode.
62c0359ff2a8 doc/Calypso-TCH-downlink: document use of tools on voice memos
Mychaela Falconia <falcon@freecalypso.org>
parents: 168
diff changeset
116 However, if the objective is to play that VM recording and not just look at
62c0359ff2a8 doc/Calypso-TCH-downlink: document use of tools on voice memos
Mychaela Falconia <falcon@freecalypso.org>
parents: 168
diff changeset
117 parsed bits, the correct approach is to convert the VM file to gsmx with
62c0359ff2a8 doc/Calypso-TCH-downlink: document use of tools on voice memos
Mychaela Falconia <falcon@freecalypso.org>
parents: 168
diff changeset
118 fc-vm2gsmx, and then decode with gsmfr-decode. Using fc-vm2hex followed by
62c0359ff2a8 doc/Calypso-TCH-downlink: document use of tools on voice memos
Mychaela Falconia <falcon@freecalypso.org>
parents: 168
diff changeset
119 gsmfr-dlcap-gsmx instead of fc-vm2gsmx won't work!
475
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
120
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
121 Catching the output of the network-side speech encoder
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
122 ======================================================
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
123
482
5e2d849a4fbc doc/Calypso-TCH-downlink: grammar fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 475
diff changeset
124 The set of FR1 test sequences included with later versions of GSM 06.10 spec
475
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
125 and the set of EFR test sequences in GSM 06.54 include special synchronization
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
126 sequences that can be fed to the G.711 PCMA or PCMU input of the TRAU in the
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
127 downlink direction, and the set of 160 possible speech encoder outputs for each
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
128 codec that can result from the TRAU processing that DL input, depending on the
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
129 alignment between the input and the location of 20 ms frame boundaries for the
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
130 encoder. In the case of EFR, there is a second dimension of uncertainty when
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
131 experimenting with GSM networks that aren't your own: in addition to the unknown
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
132 alignment of G.711 input (160 possibilities), there is the unknown of whether
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
133 the network transcoder implements classic EFR or an AMR-EFR hybrid - see our
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
134 AMR-EFR-philosophy and AMR-EFR-hybrid-emu articles. However, thanks to the work
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
135 we did in vband-misc Hg repository, we now have a fully backward-compatible
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
136 extended version of ETSI's seqsync[au].inp TRAU DL inputs (the last frame of
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
137 160 samples that isn't EHF is simply repeated twice) that allows us to
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
138 distinguish between two possible styles of EFR implementation in the network
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
139 transcoder, producing 320 possible outputs on GSM Um DL for 160 possible
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
140 alignments times two possible EFR implementation options.
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
141
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
142 However, tools are still needed on the GSM MS side of the test setup, reading
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
143 the TCH DL capture produced with FreeCalypso tools and detecting which of the
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
144 possible 160 (FR1) or 320 (EFR) encoded frames have been produced. (320 or
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
145 even 160 possible frames is too many to check by hand!) These tools are
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
146 provided in gsmfr-dlcap-sync and gsmefr-dlcap-sync, added to Themyscira GSM
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
147 codec libraries and utilities suite as of gsm-codec-lib-r3. Each of these
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
148 utilities takes two command line arguments: the name of TCH DL capture file to
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
149 read and analyze, and an "alaw" or "ulaw" keyword argument selecting the match
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
150 table to use. Specify alaw if you are feeding seqsynca.inp to a PCMA-native
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
151 TRAU or other GSM network speech transcoder, or ulaw if you are feeding
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
152 seqsyncu.inp to a PCMU-native network. The program will read the entire TCH DL
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
153 capture, looking for matches, and will report any matches it finds.
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
154
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
155 Both gsmfr-dlcap-sync and gsmefr-dlcap-sync implement the logic of looking for
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
156 the respective codec's DHF followed by one of 160 (FR1) or 320 (EFR) distinct
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
157 encoded frames. In the case of EFR, if the network transcoder implements
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
158 AMR-EFR and the alignment shift happens to be in the [120,159] range, there
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
159 will also be an MR122 DHF sandwiched between the standard EFR DHF and the
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
160 distinct encoded frame (unique for each of the 40 possible alignments in this
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
161 range) if the AMR-EFR hybrid is implemented like our amr_dhf_subst_efr2()
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
162 function, matching the network of T-Mobile USA. gsmefr-dlcap-sync looks for
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
163 both EFR and MR122 DHF; in the case of matches to AMR-EFR offset [120,159], the
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
164 tool's indication whether the unique frame was preceded by EFR or MR122 DHF
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
165 indicates how the alien network transcoder implements its DHF transformation;
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
166 in the case of other matches, seeing MR122 DHF is an unexpected error condition,
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
167 and it is reported as such.
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
168
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
169 These tools cover just one step in the workflow of reverse-engineering an alien
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
170 GSM network's speech transcoder and confirming if it matches standard EFR or
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
171 the AMR-EFR hybrid as currently found in the wild. The complete workflow in
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
172 the GSM downlink direction will typically be as follows:
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
173
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
174 1) Using sipout-test-voice utility from the sipout-test-utils suite, establish
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
175 a test call from IP-PSTN to a test MS served by the GSM network under study.
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
176 AT%SPVER will typically need to be used to cause the network to assign the
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
177 desired codec on this call.
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
178
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
179 2) While making a TCH DL recording on the FreeCalypso MS used in this test,
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
180 play seqsync[au].inp (or the extended version with the last frame sent twice)
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
181 into the G.711 PCM stream from IP-PSTN side, using 'play' command of
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
182 sipout-test-voice.
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
183
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
184 3) Run gsmfr-dlcap-sync or gsmefr-dlcap-sync on the DL recording from the
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
185 previous step, as appropriate.
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
186
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
187 4) Once the alignment is known, use 'play-offset' command in sipout-test-voice
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
188 to play a longer test sequence into the same call, and have another TCH DL
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
189 recording running on the test MS.
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
190
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
191 5) If the longer test sequence begins with the same seqsync[au].inp preamble
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
192 (which is recommended), playing it with the correct offset from IP-PSTN side
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
193 should result in gsm[e]fr-dlcap-sync reporting zero offset on the new DL
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
194 recording. However, gsm[e]fr-dlcap-sync on this second DL capture should
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
195 indicate the line number where the interesting part begins.
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
196
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
197 6) Extract the part of interest identified in the previous step, convert it to
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
198 gsmx format with gsm[e]fr-dlcap-gsmx, and compare it against the expected
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
199 encoded frame sequence.