FreeCalypso > hg > freecalypso-sw

comparison doc/TCH-special-feature @ 1017:759b3cbf46aa

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/TCH-special-feature: document written
author Mychaela Falconia <falcon@ivan.Harhan.ORG>
date Mon, 21 Mar 2016 06:05:57 +0000
parents
children 5ab737ac3ad7
comparison
equal deleted inserted replaced
1016:a6ca9ee289f7 1017:759b3cbf46aa
1 FreeCalypso GSM 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) can be non-invasively intercepted and forwarded to
8 the external host connected to the RVTMUX serial interface;
9
10 * Using the same serial interface, the external host can supply substitute
11 uplink TCH bits which will be transmitted in the place of the built-in
12 vocoder output, i.e., the latter can be effectively suppressed.
13
14 In order to use this feature, you need to compile our firmware in the voice+SMS
15 pseudo-modem configuration, i.e., the configuration in which the fw expects to
16 be controlled via AT commands wrapped in the RVTMUX binary packet serial
17 interface. You can use a target GSM device that has just one accessible serial
18 port (Mot C1xx and Pirelli DP-L10) or one that has two Calypso UARTs (Openmoko
19 GTA02 or our future FCDEV3B), but in the latter case you will be using only one
20 UART - whichever one you have configured to be RVTMUX.
21
22 Whatever system you are building that will act as the source and sink for TCH
23 bits will need to interface to the FreeCalypso GSM device via a serial port in
24 the RVTMUX binary packet format. Your system will need to send RVTMUX packets
25 with AT commands inside them in order to command the FC GSM device to register
26 with the network and to dial and/or answer calls, and you will need to send
27 RVTMUX packets of a different kind in order to supply the uplink TCH bits
28 during calls. In the other direction, your system will receive responses to
29 the AT commands you send, asynchronous notifications of incoming calls and SMS,
30 downlink TCH bits and various debug trace output from our FreeCalypso firmware.
31 The last part (debug trace output) can be simply ignored and discarded if you
32 wish, but we strongly recommend that you provide a way to view and/or log it
33 for debugging purposes.
34
35 Please see the RVTMUX document for general background information regarding the
36 RVTMUX binary packet interface; this document should be considered required
37 reading for anyone interested in working with the TCH rerouting special feature.
38
39 All packets transferred over the RVTMUX interface begin and end with 0x02. If
40 a payload byte within a packet equals 0x02 or 0x10, it needs to be prepended
41 with 0x10 as a transparency escape; all other payload bytes are sent literally.
42 The first byte within each RVTMUX packet after the opening 0x02 is the packet
43 type; the two packet types you will need to handle (both generate and receive)
44 are 0x1A for AT commands and 0x1C for TCH configuration commands.
45
46 To send an AT command to the FreeCalypso GSM device, prepend the 0x1A packet
47 type in front of the "AT" characters, wrap the packet with 0x02 bytes on both
48 ends, and send it to the modem. Responses to AT commands and asynchronous
49 notification messages such as "RING" for incoming calls will be sent to the
50 host as RVTMUX packets also beginning with the 0x1A packet type; they will be
51 interspersed among other packet types, mostly debug trace output. Your system
52 will need to receive the RVTMUX serial byte stream continuously, parsing the
53 packet structure and looking at the type of each packet (the first byte after
54 the opening 0x02) in order to detect if the modem has sent something you may be
55 interested in.
56
57 If you wish to receive a copy of all downlink TCH bits on the serial channel,
58 you will need to send the following 5-byte command packet to the modem:
59
60 0x02: opening flag
61 0x1C: RVTMUX packet type for TCH
62 0x11: TCH_CONFIG_REQ command opcode
63 0x01: payload byte indicating that the "forward downlink" state should be
64 set to enabled
65 0x02: closing flag
66
67 The modem will respond with a TCH_CONFIG_CONF confirmation message (opcode
68 0x12), and then during all voice calls your external host will receive the
69 following packet every 20 ms:
70
71 0x02: opening flag
72 0x1C: RVTMUX packet type for TCH
73 0x15: TCH_DLBITS_IND opcode
74 - 40 (decimal) bytes of payload -
75 0x02: closing flag
76
77 The 40 bytes of payload sent in every TCH_DLBITS_IND packet directly correspond
78 to the 20 16-bit words provided by the Calypso DSP in its a_dd_0 buffer. The
79 first 3 words (6 bytes) contains the DSP's own status information (not fully
80 understood by us yet, but we let you see what the DSP tells us without redacting
81 anything out), and the remaining 17 words (34 bytes) are supposed to contain
82 the TCH bits received from the GSM network in the FR codec format.
83
84 If you wish to send your own TCH uplink bits, replacing the output of the
85 built-in vocoder with your own alternate uplink data, you will need to send
86 your uplink TCH bits to the modem in packets of the following format:
87
88 0x02: opening flag
89 0x1C: RVTMUX packet type for TCH
90 0x13: TCH_ULBITS_REQ opcode
91 - 33 or 34 (decimal) bytes of payload -
92 0x02: closing flag
93
94 Sending 260 bits requires only 33 bytes, but the DSP operates in terms of
95 16-bit words, hence 17 of those words are used. The upper byte of the last
96 word is not expected to be used, but if you send 34 bytes rather than 33, you
97 will have control over every bit going into the DSP API RAM in this case.
98
99 There is a queue inside the firmware in which these TCH uplink data blocks are
100 stored; this queue is filled by the serial packet receiving handler and drained
101 by the L1S (synchronous) code that executes at the right times in the GSM TDMA
102 multiplex when uplink TCH transmission is expected. Up to 4 blocks can be
103 queued up; as each queued-up block is transmitted on the air (more precisely,
104 as it is passed to the DSP for channel encoding and transmission), a
105 TCH_ULBITS_CONF short packet (consisting of just the opcode and nothing more)
106 is sent to the host. These confirmation packets can be used to pace the sending
107 of further TCH_ULBITS_REQs.
108
109 Testing
110 =======
111
112 The just-described mechanism has been tested to the following extent: I have
113 sent TCH_CONFIG_REQ packets to the modem, requesting that TCH downlink
114 forwarding be enabled or disabled, and observed that the flow of TCH_DLBITS_IND
115 packets from the modem to the host starts and stops as expected. I have not
116 done any further work to verify the correctness of the FR codec payload bits
117 within these packets. However, the TCH uplink substitution mechanism has not
118 been tested at all, as I do not have a source of FR codec bits for testing.
119
120 Host side reference implementation
121 ==================================
122
123 If you are going to implement your system for talking to FreeCalypso GSM pseudo-
124 modems via the RVTMUX binary packet interface, we strongly recommend that you
125 use our rvinterf and fc-shell Unix/Linux host utilities as your starting point.
126 You can find their source code in the rvinterf subtree.