FreeCalypso > hg > gsm-codec-lib

annotate doc/Calypso-TCH-downlink @ 585:3c6bf0d26ee7 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
TW-TS-005 reader: fix maximum line length bug TW-TS-005 section 4.1 states: The maximum allowed length of each line is 80 characters, not including the OS-specific newline encoding. The implementation of this line length limit in the TW-TS-005 hex file reader function in the present suite was wrong, such that lines of the full maximum length could not be read. Fix it. Note that this bug affects comment lines too, not just actual RTP payloads. Neither Annex A nor Annex B features an RTP payload format that goes to the maximum of 40 bytes, but if a comment line goes to the maximum allowed length of 80 characters not including the terminating newline, the bug will be triggered, necessitating the present fix.
author Mychaela Falconia <falcon@freecalypso.org>
date Tue, 25 Feb 2025 07:49:28 +0000
parents 18aca50d68df
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
556
18aca50d68df doc/Calypso-TCH-downlink: update for FR1 BFI-with-data
Mychaela Falconia <falcon@freecalypso.org>
parents: 482
diff changeset
113 [Update: as of libgsmfr2 version 2.1.0, the above paragraph is no longer fully
18aca50d68df doc/Calypso-TCH-downlink: update for FR1 BFI-with-data
Mychaela Falconia <falcon@freecalypso.org>
parents: 482
diff changeset
114 correct. The new version of our Rx DTX handler does look at bad traffic frames
18aca50d68df doc/Calypso-TCH-downlink: update for FR1 BFI-with-data
Mychaela Falconia <falcon@freecalypso.org>
parents: 482
diff changeset
115 (BFI=1) in order to catch those that should be handled as invalid SID rather
18aca50d68df doc/Calypso-TCH-downlink: update for FR1 BFI-with-data
Mychaela Falconia <falcon@freecalypso.org>
parents: 482
diff changeset
116 than unusable frame classification, and our original gsmx binary file format
18aca50d68df doc/Calypso-TCH-downlink: update for FR1 BFI-with-data
Mychaela Falconia <falcon@freecalypso.org>
parents: 482
diff changeset
117 is thus no longer sufficient to match the full capabilities of our library.
18aca50d68df doc/Calypso-TCH-downlink: update for FR1 BFI-with-data
Mychaela Falconia <falcon@freecalypso.org>
parents: 482
diff changeset
118 The new hexadecimal file format of TW-TS-005 Annex A solves this shortcoming -
18aca50d68df doc/Calypso-TCH-downlink: update for FR1 BFI-with-data
Mychaela Falconia <falcon@freecalypso.org>
parents: 482
diff changeset
119 but the present suite of Calypso TCH downlink utilities is currently a low
18aca50d68df doc/Calypso-TCH-downlink: update for FR1 BFI-with-data
Mychaela Falconia <falcon@freecalypso.org>
parents: 482
diff changeset
120 priority, hence no code updates are currently being worked on in this area.]
18aca50d68df doc/Calypso-TCH-downlink: update for FR1 BFI-with-data
Mychaela Falconia <falcon@freecalypso.org>
parents: 482
diff changeset
121
180
62c0359ff2a8 doc/Calypso-TCH-downlink: document use of tools on voice memos
Mychaela Falconia <falcon@freecalypso.org>
parents: 168
diff changeset
122 * 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
123 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
124 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
125 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
126 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
127 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
128 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
129
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
130 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
131 ======================================================
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
132
482
5e2d849a4fbc doc/Calypso-TCH-downlink: grammar fix
Mychaela Falconia <falcon@freecalypso.org>
parents: 475
diff changeset
133 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
134 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
135 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
136 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
137 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
138 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
139 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
140 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
141 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
142 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
143 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
144 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
145 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
146 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
147 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
148 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
149 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
150
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
151 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
152 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
153 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
154 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
155 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
156 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
157 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
158 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
159 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
160 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
161 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
162 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
163
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
164 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
165 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
166 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
167 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
168 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
169 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
170 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
171 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
172 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
173 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
174 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
175 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
176 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
177
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
178 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
179 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
180 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
181 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
182
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
183 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
184 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
185 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
186 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
187
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
188 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
189 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
190 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
191 sipout-test-voice.
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
192
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
193 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
194 previous step, as appropriate.
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
195
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
196 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
197 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
198 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
199
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
200 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
201 (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
202 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
203 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
204 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
205
e512f0d25409 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync
Mychaela Falconia <falcon@freecalypso.org>
parents: 304
diff changeset
206 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
207 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
208 encoded frame sequence.