FreeCalypso > hg > freecalypso-citrine

comparison doc/TCH-special-feature @ 28:cb00b90edaff

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
documentation write-ups imported from freecalypso-sw and updated for Citrine
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 12 Jun 2016 18:28:35 +0000
parents
children 3362a76ab432
comparison
equal deleted inserted replaced
27:3ecd6054a7f7 28:cb00b90edaff
1 FreeCalypso Citrine firmware implements an optional special feature (needs to be
2 explicitly enabled at compile time) which we call TCH rerouting. When this
3 feature is enabled, it applies the following special handling to GSM voice
4 traffic channels (TCH):
5
6 * All downlink TCH bits passing from the channel decoder to the vocoder block
7 (260 bits every 20 ms with the original FR codec) can be non-invasively
8 intercepted and forwarded to the external host connected to the RVTMUX serial
9 interface;
10
11 * Using the same serial interface, the external host can supply substitute
12 uplink TCH bits which will be transmitted in the place of the built-in
13 vocoder output, i.e., the latter can be effectively suppressed.
14
15 In order to use this feature, you need to compile our firmware in the voice+SMS
16 pseudo-modem configuration, i.e., the configuration in which the fw expects to
17 be controlled via AT commands wrapped in the RVTMUX binary packet serial
18 interface. You can use a target GSM device that has just one accessible serial
19 port (Mot C1xx and Pirelli DP-L10) or one that has two Calypso UARTs (Openmoko
20 GTA02 or our future FCDEV3B), but in the latter case you will be using only one
21 UART - whichever one you have configured to be RVTMUX.
22
23 Whatever system you are building that will act as the source and sink for TCH
24 bits will need to interface to the FreeCalypso GSM device via a serial port in
25 the RVTMUX binary packet format. Your system will need to send RVTMUX packets
26 with AT commands inside them in order to command the FC GSM device to register
27 with the network and to dial and/or answer calls, and you will need to send
28 RVTMUX packets of a different kind in order to supply the uplink TCH bits
29 during calls. In the other direction, your system will receive responses to
30 the AT commands you send, asynchronous notifications of incoming calls and SMS,
31 downlink TCH bits and various debug trace output from our FreeCalypso firmware.
32 The last part (debug trace output) can be simply ignored and discarded if you
33 wish, but we strongly recommend that you provide a way to view and/or log it
34 for debugging purposes.
35
36 Please see the RVTMUX document in the FreeCalypso host tools package for general
37 background information regarding the RVTMUX binary packet interface; this
38 document should be considered required reading for anyone interested in working
39 with the TCH rerouting special feature.
40
41 All packets transferred over the RVTMUX interface begin and end with 0x02. If
42 a payload byte within a packet equals 0x02 or 0x10, it needs to be prepended
43 with 0x10 as a transparency escape; all other payload bytes are sent literally.
44 The first byte within each RVTMUX packet after the opening 0x02 is the packet
45 type; the two packet types you will need to handle (both generate and receive)
46 are 0x1A for AT commands and 0x1C for TCH configuration commands.
47
48 To send an AT command to the FreeCalypso GSM device, prepend the 0x1A packet
49 type in front of the "AT" characters, wrap the packet with 0x02 bytes on both
50 ends, and send it to the modem. Responses to AT commands and asynchronous
51 notification messages such as "RING" for incoming calls will be sent to the
52 host as RVTMUX packets also beginning with the 0x1A packet type; they will be
53 interspersed among other packet types, mostly debug trace output. Your system
54 will need to receive the RVTMUX serial byte stream continuously, parsing the
55 packet structure and looking at the type of each packet (the first byte after
56 the opening 0x02) in order to detect if the modem has sent something you may be
57 interested in.
58
59 If you wish to receive a copy of all downlink TCH bits on the serial channel,
60 you will need to send the following 5-byte command packet to the modem:
61
62 0x02: opening flag
63 0x1C: RVTMUX packet type for TCH
64 0x11: TCH_CONFIG_REQ command opcode
65 0x01: payload byte indicating that the "forward downlink" state should be
66 set to enabled
67 0x02: closing flag
68
69 The modem will respond with a TCH_CONFIG_CONF confirmation message (opcode
70 0x12), and then during all voice calls your external host will receive the
71 following packet every 20 ms:
72
73 0x02: opening flag
74 0x1C: RVTMUX packet type for TCH
75 0x15: TCH_DLBITS_IND opcode
76 - 40 (decimal) bytes of payload -
77 0x02: closing flag
78
79 The 40 bytes of payload sent in every TCH_DLBITS_IND packet directly correspond
80 to the 20 16-bit words provided by the Calypso DSP in its a_dd_0 buffer. The
81 first 3 words (6 bytes) contains the DSP's own status information (not fully
82 understood by us yet, but we let you see what the DSP tells us without redacting
83 anything out), and the remaining 17 words (34 bytes) are supposed to contain
84 the TCH bits received from the GSM network in the FR codec format. Each DSP
85 API word is sent in the big-endian byte order, i.e., the most significant byte
86 followed by the least significant byte.
87
88 If you wish to send your own TCH uplink bits, replacing the output of the
89 built-in vocoder with your own alternate uplink data, you will need to send
90 your uplink TCH bits to the modem in packets of the following format:
91
92 0x02: opening flag
93 0x1C: RVTMUX packet type for TCH
94 0x13: TCH_ULBITS_REQ opcode
95 - 33 or 34 (decimal) bytes of payload -
96 0x02: closing flag
97
98 Sending 260 bits requires only 33 bytes, but the DSP operates in terms of
99 16-bit words, hence 17 of those words are used. The least significant byte of
100 the last word (i.e., the very last byte with our big-endian transmission order)
101 is not expected to be used, but if you send 34 bytes rather than 33, you will
102 have control over every bit going into the DSP API RAM in this case.
103
104 There is a queue inside the firmware in which these TCH uplink data blocks are
105 stored; this queue is filled by the serial packet receiving handler and drained
106 by the L1S (synchronous) code that executes at the right times in the GSM TDMA
107 multiplex when uplink TCH transmission is expected. Up to 4 blocks can be
108 queued up; as each queued-up block is transmitted on the air (more precisely,
109 as it is passed to the DSP for channel encoding and transmission), a
110 TCH_ULBITS_CONF short packet (consisting of just the opcode and nothing more)
111 is sent to the host. These confirmation packets can be used to pace the sending
112 of further TCH_ULBITS_REQs.
113
114 Testing
115 =======
116
117 The just-described mechanism has been tested as follows:
118
119 1. I placed a call to WWV (+1-303-499-7111), and after verifying with my ear
120 that the downlink audio was good, I recorded the downlink TCH bits on that
121 call into a file with the tch record command in fc-shell.
122
123 2. I placed a call to another phone (running over a live commercial GSM network)
124 and played the saved recording from WWV into the call uplink with the
125 tch play command in fc-shell.
126
127 3. The audio heard on the other end of the call in the previous step: the
128 recording from WWV was definitely recognizable, but it didn't sound perfect,
129 i.e., it was rather garbled.
130
131 [NOTE: the experiment described above was performed with an older version of
132 the firmware which is now codenamed Citrine, namely, the version with L1-2014.
133 I have not played with the TCH rerouting feature again since the transition to
134 L1-2016.]
135
136 Further debugging of this mechanism will require two things which I currently
137 lack: (1) proper understanding of the workings of the GSM 06.10 FR codec and
138 (2) a test GSM network (as in OpenBTS/OpenBSC/etc) that could be used instead
139 of live commercial ones, so we could see exactly what the test MS is
140 transmitting on the air and what the BTS transmits in the downlink.
141
142 Host side reference implementation
143 ==================================
144
145 If you are going to implement your own system for talking to FreeCalypso GSM
146 pseudo-modems via the RVTMUX binary packet interface, we strongly recommend
147 that you use our rvinterf and fc-shell Unix/Linux host utilities as your
148 starting point. You can find their source code in the freecalypso-tools Hg
149 repository on Bitbucket.
150
151 The following test commands have been added to fc-shell for exercising the
152 experimental TCH rerouting mechanism:
153
154 tch record <filename>
155
156 Sends a TCH_CONFIG_REQ packet to the target, commanding the firmware to
157 start forwarding TCH downlink bits to the external host, and starts
158 recording the bits it receives in the named file. The file is written
159 with the same ordering of GSM 06.10 bits as used by the popular libgsm
160 implementation of this codec, i.e., the bits received from the GSM
161 device (ultimately coming from TI's DSP) are reordered before being
162 written into the file. It is only a reordering of bits with no change
163 in the information content.
164
165 I was hoping that the resulting files could be played with the SoX play
166 command under Slackware Linux, but all I got was garbled audio, and my
167 audio-fu is not good enough to figure out what is wrong.
168
169 tch record stop
170
171 Stops TCH downlink recording and closes the file into which the bytes
172 were being written; until the file is thus closed, it may not be
173 actually written out to the file system.
174
175 tch play <filename>
176
177 Plays GSM 06.10 FR speech frames from the named file in libgsm format
178 (same as written by the tch record command) into the call uplink.
179
180 tch play stop
181
182 Terminates the TCH UL play-from-file operation. This command is
183 normally not needed, as the play session will end automatically when
184 the end of file is reached.