Project

General

Profile

Osmo-tetra » History » Version 18

laforge, 02/21/2016 10:07 AM

1 15 horiz0n
{{>toc}}
2 1 laforge
3 15 horiz0n
h1. Osmocom TETRA MAC/PHY layer experimentation code
4
5
6 1 laforge
This code aims to implement the sending and receiving part of the
7
TETRA MAC/PHY layer.
8
9
If you read the ETSI EN 300 392-2 (TETRA V+D Air Interface), you will
10
find this code implementing the parts between the MAC-blocks (called
11
type-1 bits) and the bits that go to the DQPSK-modulator (type-5 bits).
12
13
It is most useful to look at Figure 8.5, 8.6, 9.3 and 19.12 of the
14
abovementioned specification in conjunction with this program.
15
16
17 15 horiz0n
h2. Big picture
18
19
20 16 laforge
{{graphviz_link()
21 1 laforge
digraph G {
22
  graph [ rankdir = LR ];
23
24
  bits_file2 -> tetra_rx [ label = "read" ];
25
  tetra_rx -> console [ label = "stdout" ];
26
  tetra_rx -> wireshark [ label = "GSMTAP" ];
27
28
  float_file2 -> float_to_bits [ label = "read" ];
29
  float_to_bits -> bits_file1 [ label = "write" ];
30
31
  USRP -> tetra_demod [ label = "USB" ];
32
  tetra_demod -> float_file1 [ label = "write" ];
33
34
  bits_file1 [ shape=box label="file.bits" ];
35
  bits_file2 [ shape=box label="file.bits" ];
36
  float_file1 [ shape=box label="file.float" ];
37
  float_file2 [ shape=box label="file.float" ];
38
  tetra_rx [ label="tetra-rx" ];
39
  tetra_demod [ label="tetra-demod.py" ];
40 15 horiz0n
}
41 16 laforge
}}
42 15 horiz0n
43
h2. Source Code
44
45 1 laforge
The source code is available via read-only git access at
46 15 horiz0n
<pre>
47 1 laforge
git clone git://git.osmocom.org/osmo-tetra.git
48 15 horiz0n
</code></pre>
49 1 laforge
50
You can also browse the source code at http://cgit.osmocom.org/
51
52 15 horiz0n
You will need "libosmocore":http://bb.osmocom.org/trac/wiki/libosmocore to link.
53 1 laforge
54 15 horiz0n
55
h2. Mailing List
56
57 1 laforge
There is a public mailing list regarding development of this project, you can
58
visit the subscription page at https://lists.osmocom.org/mailman/listinfo/tetra
59
60 15 horiz0n
This list is *for discussion between software developers* who intend to improve the
61 1 laforge
Osmocom TETRA software.  It is not a forum for individuals asking how they can tap
62 2 horiz0n
into police radio (which is encrypted anyway).
63 1 laforge
64
65 15 horiz0n
h2. FAQ
66 1 laforge
67 15 horiz0n
We now have a [[FAQ]] (Frequently asked Questions) page!
68 1 laforge
69 15 horiz0n
h2. Demodulator
70 1 laforge
71 18 laforge
<pre>
72
src/demod/python/cpsk.py
73
</pre>
74 1 laforge
75 18 laforge
* contains a gnuradio based pi4/DQPSK demodulator, courtesy of KA1RBI
76
77 1 laforge
<pre>
78 18 laforge
src/demod/python/tetra-demod.py
79
</pre>
80
81
* call demodulator on a 'cfile' containing complex baseband samples
82
83 1 laforge
<pre>
84 18 laforge
src/demod/python/usrp1-tetra_demod.py
85
</pre>
86
87
* use demodulator in realtime with a USRP1 SDR
88
89 1 laforge
<pre>
90 18 laforge
src/demod/python/usrp2-tetra_demod.py
91
</pre>
92
93
* use demodulator in realtime with a USRP2 SDR
94
95 1 laforge
<pre>
96 18 laforge
src/demod/python/fcdp-tetra_demod.py
97
src/demod/python/fcdp-tetra_demod_fft.py
98
</pre>
99 1 laforge
100 18 laforge
* use demodulator in realtime with a [[Funcube_Dongle]]. Please use the "qthid":https://github.com/csete/qthid application to tune the dongle and adjust its gain/filter parameters for best reception result. This demodulator may also be used with other Softrock-type receivers by downconverting the intermediate frequency of a radio scanner to the complex baseband.
101
102 15 horiz0n
The output of the demodulator is a file containing one float value for each symbol,
103 1 laforge
containing the phase shift (in units of pi/4) relative to the previous symbol.
104
105 18 laforge
You can use the @float_to_bits@ program to convert the float values to unpacked bits, i.e. 1-bit-per-byte
106 1 laforge
107
108
h2. PHY/MAC layer
109
110
111
h3. library code
112
113
114
Specifically, it implements:
115
116
<pre>
117 18 laforge
lower_mac/crc_simple.[ch]
118
</pre>
119
120
* CRC16-CCITT (currently defunct/broken as we need it for non-octet-aligned bitfields)
121
122 1 laforge
<pre>
123 18 laforge
lower_mac/tetra_conv_enc.[ch]
124
</pre>
125
126
* 16-state Rate-Compatible Punctured Convolutional (RCPC) coder
127
128 1 laforge
<pre>
129 18 laforge
lower_mac/tetra_interleave.[ch]
130
</pre>
131
132
* Block interleaving (over a single block only)
133
134 1 laforge
<pre>
135 18 laforge
lower_mac/tetra_rm3014.[ch]
136
</pre>
137
138
* (30, 14) Reed-Muller code for the ACCH (broadcast block of each downlink burst)
139
140 1 laforge
<pre>
141 18 laforge
lower_mac/tetra_scramb.[ch]
142
</pre>
143 1 laforge
144 18 laforge
* Scrambling
145 1 laforge
146 18 laforge
<pre>
147
lower_mac/viterbi*.[ch]
148
</pre>
149 15 horiz0n
150 18 laforge
* Convolutional decoder for signalling and voice channels
151 1 laforge
152 18 laforge
<pre>
153
phy/tetra_burst.[ch]
154
</pre>
155 15 horiz0n
156 18 laforge
* Routines to encode continuous normal and sync bursts
157
158 1 laforge
<pre>
159 18 laforge
phy/tetra_burst_sync.[ch]
160
</pre>
161 1 laforge
162
163 18 laforge
h3. Receiver Program
164 3 horiz0n
165 18 laforge
The main receiver program @tetra-rx@ expects an input file containing a stream of unpacked bits, i.e. 1-bit-per-byte.
166
167 15 horiz0n
h3. Transmitter Program
168
169 18 laforge
The main program conv_enc_test.c generates a single continuous downlink sync burst (SB), containing:
170
* a SYNC-PDU as block 1
171
* a ACCESS-ASSIGN PDU as broadcast block
172
* a SYSINFO-PDU as block 2
173 5 horiz0n
174 13 horiz0n
Scrambling is set to 0 (no scrambling) for all elements of the burst.
175 11 horiz0n
176 15 horiz0n
It does not actually modulate and/or transmit yet.
177 1 laforge
178 11 horiz0n
179 14 horiz0n
h2. Quick example
180
181 18 laforge
assuming you have generated a file @samples.cfile@ at a sample rate of 195.312kHz (100MHz/512 == USRP2 at decimation 512)
182 10 horiz0n
183 6 horiz0n
<pre>
184 10 horiz0n
./src/demod/python/tetra-demod.py -i /tmp/samples.cfile -o /tmp/out.float -s 195312 -c 0
185 5 horiz0n
./src/float_to_bits /tmp/out.float /tmp/out.bits
186 15 horiz0n
./src/tetra-rx /tmp/out.bits
187 18 laforge
</pre>
188 1 laforge
189
Also, you may use pipes to glue the three programs running in different terminals together to achieve real time operation.
190 15 horiz0n
191
<pre>
192
mkfifo /tmp/out.float
193
mkfifo /tmp/out.bits
194
./src/demod/python/fcdp-tetra_demod.py -D hw:1,0 -o /tmp/out.float
195
...
196 18 laforge
</pre>
197 15 horiz0n
198 17 laforge
The most user friendly way is the script osmosdr-tetra_demod_fft.py which is based on "gr-osmosdr":http://sdr.osmocom.org/trac/wiki/GrOsmoSDR and supports various radio hardware (OsmoSDR, RTLSDR, FCD, UHD) as well as IQ file input.
199 1 laforge
200
* Adjust the center frequency (-f) and gain (-g) according to your needs.
201
* Use left click in Wideband Spectrum window to roughly select a TETRA carrier.
202 15 horiz0n
* In Wideband Spectrum you may also tune by 1/4 of the bandwidth at once by clicking on the rightmost/leftmost spectrum side.
203 1 laforge
* Use left click in Channel Spectrum window to fine tune the carrier by clicking on the left or right side of the spectrum.
204 15 horiz0n
205 1 laforge
!osmo-tetra-demod.png!
206
207
For live capture call:
208
209
<pre>
210 15 horiz0n
src$ ./demod/python/osmosdr-tetra_demod_fft.py -o /dev/stdout | ./float_to_bits /dev/stdin /dev/stdout | ./tetra-rx /dev/stdin
211 18 laforge
</pre>
212 15 horiz0n
213 1 laforge
You may specify gr-osmosdr device arguments by using the --args commandline option.
214
215
To use a gnuradio .cfile as input:
216
217
<pre>
218
src$ ./demod/python/osmosdr-tetra_demod_fft.py -a "file=/path/to/tetra_sps1024e3.cfile,rate=1024e3,repeat=true,throttle=true" -o /dev/stdout | ./float_to_bits /dev/stdin /dev/stdout | ./tetra-rx /dev/stdin
219 18 laforge
</pre>
220 1 laforge
221
Note the mandatory rate argument and optional repeat & throttle arguments.
Add picture from clipboard (Maximum size: 48.8 MB)