# HG changeset patch # User Mychaela Falconia # Date 1715991206 0 # Node ID e512f0d254093a79a409199a8322cfa9bcc2b0bd # Parent 285381a001fc6c450b76a901337b720d3249f565 doc/Calypso-TCH-downlink: document gsm[e]fr-dlcap-sync diff -r 285381a001fc -r e512f0d25409 doc/Calypso-TCH-downlink --- a/doc/Calypso-TCH-downlink Wed May 15 06:20:59 2024 +0000 +++ b/doc/Calypso-TCH-downlink Sat May 18 00:13:26 2024 +0000 @@ -117,3 +117,83 @@ parsed bits, the correct approach is to convert the VM file to gsmx with fc-vm2gsmx, and then decode with gsmfr-decode. Using fc-vm2hex followed by gsmfr-dlcap-gsmx instead of fc-vm2gsmx won't work! + +Catching the output of the network-side speech encoder +====================================================== + +The set of FR1 test sequences included with later versions of GSM 06.10 specs +and the set of EFR test sequences in GSM 06.54 include special synchronization +sequences that can be fed to the G.711 PCMA or PCMU input of the TRAU in the +downlink direction, and the set of 160 possible speech encoder outputs for each +codec that can result from the TRAU processing that DL input, depending on the +alignment between the input and the location of 20 ms frame boundaries for the +encoder. In the case of EFR, there is a second dimension of uncertainty when +experimenting with GSM networks that aren't your own: in addition to the unknown +alignment of G.711 input (160 possibilities), there is the unknown of whether +the network transcoder implements classic EFR or an AMR-EFR hybrid - see our +AMR-EFR-philosophy and AMR-EFR-hybrid-emu articles. However, thanks to the work +we did in vband-misc Hg repository, we now have a fully backward-compatible +extended version of ETSI's seqsync[au].inp TRAU DL inputs (the last frame of +160 samples that isn't EHF is simply repeated twice) that allows us to +distinguish between two possible styles of EFR implementation in the network +transcoder, producing 320 possible outputs on GSM Um DL for 160 possible +alignments times two possible EFR implementation options. + +However, tools are still needed on the GSM MS side of the test setup, reading +the TCH DL capture produced with FreeCalypso tools and detecting which of the +possible 160 (FR1) or 320 (EFR) encoded frames have been produced. (320 or +even 160 possible frames is too many to check by hand!) These tools are +provided in gsmfr-dlcap-sync and gsmefr-dlcap-sync, added to Themyscira GSM +codec libraries and utilities suite as of gsm-codec-lib-r3. Each of these +utilities takes two command line arguments: the name of TCH DL capture file to +read and analyze, and an "alaw" or "ulaw" keyword argument selecting the match +table to use. Specify alaw if you are feeding seqsynca.inp to a PCMA-native +TRAU or other GSM network speech transcoder, or ulaw if you are feeding +seqsyncu.inp to a PCMU-native network. The program will read the entire TCH DL +capture, looking for matches, and will report any matches it finds. + +Both gsmfr-dlcap-sync and gsmefr-dlcap-sync implement the logic of looking for +the respective codec's DHF followed by one of 160 (FR1) or 320 (EFR) distinct +encoded frames. In the case of EFR, if the network transcoder implements +AMR-EFR and the alignment shift happens to be in the [120,159] range, there +will also be an MR122 DHF sandwiched between the standard EFR DHF and the +distinct encoded frame (unique for each of the 40 possible alignments in this +range) if the AMR-EFR hybrid is implemented like our amr_dhf_subst_efr2() +function, matching the network of T-Mobile USA. gsmefr-dlcap-sync looks for +both EFR and MR122 DHF; in the case of matches to AMR-EFR offset [120,159], the +tool's indication whether the unique frame was preceded by EFR or MR122 DHF +indicates how the alien network transcoder implements its DHF transformation; +in the case of other matches, seeing MR122 DHF is an unexpected error condition, +and it is reported as such. + +These tools cover just one step in the workflow of reverse-engineering an alien +GSM network's speech transcoder and confirming if it matches standard EFR or +the AMR-EFR hybrid as currently found in the wild. The complete workflow in +the GSM downlink direction will typically be as follows: + +1) Using sipout-test-voice utility from the sipout-test-utils suite, establish + a test call from IP-PSTN to a test MS served by the GSM network under study. + AT%SPVER will typically need to be used to cause the network to assign the + desired codec on this call. + +2) While making a TCH DL recording on the FreeCalypso MS used in this test, + play seqsync[au].inp (or the extended version with the last frame sent twice) + into the G.711 PCM stream from IP-PSTN side, using 'play' command of + sipout-test-voice. + +3) Run gsmfr-dlcap-sync or gsmefr-dlcap-sync on the DL recording from the + previous step, as appropriate. + +4) Once the alignment is known, use 'play-offset' command in sipout-test-voice + to play a longer test sequence into the same call, and have another TCH DL + recording running on the test MS. + +5) If the longer test sequence begins with the same seqsync[au].inp preamble + (which is recommended), playing it with the correct offset from IP-PSTN side + should result in gsm[e]fr-dlcap-sync reporting zero offset on the new DL + recording. However, gsm[e]fr-dlcap-sync on this second DL capture should + indicate the line number where the interesting part begins. + +6) Extract the part of interest identified in the previous step, convert it to + gsmx format with gsm[e]fr-dlcap-gsmx, and compare it against the expected + encoded frame sequence.