1dump1090(1) Simple Mode S decoder dump1090(1)
2 SYNOPSIS
6 /usr/bin/dump1090 [--longoption ...]
7 DESCRIPTION
9 Install this to use your RTL-SDR to track commercial aircraft in your
10 area.
11 The main features are:
13 • Robust decoding of weak messages, with mode1090 many users observed
15 improved range compared to other popular decoders.
16 • Network support: TCP30003 stream (MSG5...), Raw packets, HTTP.
18 • Embedded HTTP server that displays the currently detected aircraft on
20 Google Map.
21 • Single bit errors correction using the 24 bit CRC.
23 • Ability to decode DF11, DF17 messages.
25 • Ability to decode DF formats like DF0, DF4, DF5, DF16, DF20 and DF21
27 where the checksum is xored with the ICAO address by brute forcing
28 the checksum field using recently seen ICAO addresses.
29 • Decode raw IQ samples from file (using –ifile command line switch).
31 • Interactive command-line interface mode where aircraft currently de‐
33 tected are shown as a list refreshing as more data arrives.
34 • CPR coordinates decoding and track calculation from velocity.
36 • TCP server streaming and receiving raw data to/from connected clients
38 (using –net).
39 USAGE
41 To capture traffic directly from your RTL device and show the captured
42 traffic on standard output, just run the program without options at
43 all:
44 ./dump1090
46 To just output hexadecimal messages:
48 ./dump1090 --raw
50 To run the program in interactive mode:
52 ./dump1090 --interactive
54 To run the program in interactive mode, with networking support, and
56 connect with your browser to http://localhost:8080 to see live traffic:
57 ./dump1090 --interactive --net
59 In interactive mode it is possible to have a less information dense but
61 more “arcade style” output, where the screen is refreshed every second
62 displaying all the recently seen aircrafts with some additional infor‐
63 mation such as altitude and flight number, extracted from the received
64 Mode S packets.
65 Using files as source of data
67 To decode data from file, use:
68 ./dump1090 --ifile /path/to/binfile
70 The binary file should be created using rtl_sdr like this (or with any
72 other program that is able to output 8-bit unsigned IQ samples at 2Mhz
73 sample rate).
74 rtl_sdr -f 1090000000 -s 2000000 -g 50 output.bin
76 In the example rtl_sdr a gain of 50 is used, simply you should use the
78 highest gain availabe for your tuner. This is not needed when calling
79 Dump1090 itself as it is able to select the highest gain supported au‐
80 tomatically.
81 It is possible to feed the program with data via standard input using
83 the –ifile option with “-” as argument.
84 Additional options
86 Dump1090 can be called with other command line options to set a differ‐
87 ent gain, frequency, and so forth. For a list of options use:
88 ./dump1090 --help
90 Everything is not documented here should be obvious, and for most users
92 calling it without arguments at all is the best thing to do.
93 Reliability
95 By default Dump1090 tries to fix single bit errors using the checksum.
96 Basically the program will try to flip every bit of the message and
97 check if the checksum of the resulting message matches.
98 This is indeed able to fix errors and works reliably in my experience,
100 however if you are interested in very reliable data I suggest to use
101 the –no-fix command line switch in order to disable error fixing.
102 Performances and sensibility of detection
104 In my limited experience Dump1090 was able to decode a big number of
105 messages even in conditions where I encountered problems using other
106 programs, however no formal test was performed so I can’t really claim
107 that this program is better or worse compared to other similar pro‐
108 grams.
109 If you can capture traffic that Dump1090 is not able to decode proper‐
111 ly, drop me an email with a download link. I may try to improve the
112 detection during my free time (this is just an hobby project).
113 Network server features
115 By enabling the networking support with –net Dump1090 starts listening
116 for clients connections on port 30002 and 30001 (you can change both
117 the ports if you want, see –help output).
118 Port 30002
120 Connected clients are served with data ASAP as they arrive from the de‐
121 vice (or from file if –ifile is used) in the raw format similar to the
122 following:
123 *8D451E8B99019699C00B0A81F36E;
125 Every entry is separated by a simple newline (LF character, hex 0x0A).
127 Port 30001
129 Port 30001 is the raw input port, and can be used to feed Dump1090 with
130 data in the same format as specified above, with hex messages starting
131 with a * and ending with a ; character.
132 So for instance if there is another remote Dump1090 instance collecting
134 data it is possible to sum the output to a local Dump1090 instance do‐
135 ing something like this:
136 nc remote-dump1090.example.net 30002 | nc localhost 30001
138 It is important to note that what is received via port 30001 is also
140 broadcasted to clients listening to port 30002.
141 In general everything received from port 30001 is handled exactly like
143 the normal traffic from RTL devices or from file when –ifile is used.
144 It is possible to use Dump1090 just as an hub using –ifile with
146 /dev/zero as argument as in the following example:
147 ./dump1090 --net-only
149 Or alternatively to see what’s happening on the screen:
151 ./dump1090 --net-only --interactive
153 Then you can feed it from different data sources from the internet.
155 Port 30003
157 Connected clients are served with messages in SBS1 (BaseStation) for‐
158 mat, similar to:
159 MSG,4,,,738065,,,,,,,,420,179,,,0,,0,0,0,0
161 MSG,3,,,738065,,,,,,,35000,,,34.81609,34.07810,,,0,0,0,0
162 This can be used to feed data to various sharing sites without the need
164 to use another decoder.
165 Antenna
167 Mode S messages are transmitted in the 1090 Mhz frequency. If you have
168 a decent antenna you’ll be able to pick up signals from aircrafts pret‐
169 ty far from your position, especially if you are outdoor and in a posi‐
170 tion with a good sky view.
171 You can easily build a very cheap antenna following the istructions at:
173 http://antirez.com/news/46
175 With this trivial antenna I was able to pick up signals of aircrafts
177 200+ Km away from me.
178 If you are interested in a more serious antenna check the following re‐
180 sources:
181 • http://gnuradio.org/data/grcon11/06-foster-adsb.pdf
183 • http://www.lll.lu/~edward/edward/adsb/antenna/ADSBantenna.html
185 • http://modesbeast.com/pix/adsb-ant-drawing.gif
187 Aggressive mode
189 With –aggressive it is possible to activate the aggressive mode that is
190 a modified version of the Mode S packet detection and decoding. THe
191 aggresive mode uses more CPU usually (especially if there are many
192 planes sending DF17 packets), but can detect a few more messages.
193 The algorithm in aggressive mode is modified in the following ways:
195 • Up to two demodulation errors are tolerated (adjacent entires in the
197 magnitude vector with the same eight). Normally only messages with‐
198 out errors are checked.
199 • It tries to fix DF17 messages trying every two bits combination.
201 The use of aggressive mdoe is only advised in places where there is low
203 traffic in order to have a chance to capture some more messages.
204 Debug mode
206 The Debug mode is a visual help to improve the detection algorithm or
207 to understand why the program is not working for a given input.
208 In this mode messages are displayed in an ASCII-art style graphical
210 representation, where the individial magnitude bars sampled at 2Mhz are
211 displayed.
212 An index shows the sample number, where 0 is the sample where the first
214 Mode S peak was found. Some additional background noise is also added
215 before the first peak to provide some context.
216 To enable debug mode and check what combinations of packets you can
218 log, use mode1090 --help to obtain a list of available debug flags.
219 Debug mode includes an optional javascript output that is used to visu‐
221 alize packets using a web browser, you can use the file debug.html un‐
222 der the `tools' directory to load the generated frames.js file.
223 How this program works?
225 The code is very documented and written in order to be easy to under‐
226 stand. For the diligent programmer with a Mode S specification on his
227 hands it should be trivial to understand how it works.
228 The algorithms I used were obtained basically looking at many messages
230 as displayed using a trow-away SDL program, and trying to model the al‐
231 gorithm based on how the messages look graphically.
232 How to test the program?
234 If you have an RTLSDR device and you happen to be in an area where
235 there are aircrafts flying over your head, just run the program and
236 check for signals.
237 However if you don’t have an RTLSDR device, or if in your area the
239 presence of aircrafts is very limited, you may want to try the sample
240 file distributed with the Dump1090 distribution under the “testfiles”
241 directory.
242 Just run it like this:
244 ./dump1090 --ifile testfiles/modes1.bin
246 What is –strip mode?
248 It is just a simple filter that will get raw IQ 8 bit samples in input
249 and will output a file missing all the parts of the file where I and Q
250 are lower than the specified for more than 32 samples.
251 Use it like this:
253 cat big.bin | ./dump1090 --snip 25 > small.bin
255 I used it in order to create a small test file to include inside this
257 program source code distribution.
258 Contributing
260 Dump1090 was written during some free time during xmas 2012, it is an
261 hobby project so I’ll be able to address issues and improve it only
262 during free time, however you are incouraged to send pull requests in
263 order to improve the program. A good starting point can be the TODO
264 list included in the source distribution.
265 OPTIONS
267 • --device-index <index>
268 Select RTL device (default: 0).
269 • --gain <db>
271 Set gain (default: max gain. Use -100 for auto-gain).
272 • --enable-agc
274 Enable the Automatic Gain Control (default: off).
275 • --freq <hz>
277 Set frequency (default: 1090 Mhz).
278 • --ifile <filename>
280 Read data from file (use `-' for stdin).
281 • --loop
283 With –ifile, read the same file in a loop.
284 • --interactive
286 Interactive mode refreshing data on screen.
287 • --interactive-rows <num>
289 Max number of rows in interactive mode (default: 15).
290 • --interactive-ttl <sec>
292 Remove from list if idle for (default: 60).
293 • --raw
295 Show only messages hex values.
296 • --net
298 Enable networking.
299 • --net-only
301 Enable just networking, no RTL device or file used.
302 • --net-ro-port <port>
304 TCP listening port for raw output (default: 30002).
305 • --net-ri-port <port>
307 TCP listening port for raw input (default: 30001).
308 • --net-http-port <port>
310 HTTP server port (default: 8080).
311 • --net-sbs-port <port>
313 TCP listening port for BaseStation format output (default: 30003).
314 • --no-fix
316 Disable single-bits error correction using CRC.
317 • --no-crc-check
319 Disable messages with broken CRC (discouraged).
320 • --aggressive
322 More CPU for more messages (two bits fixes, ...).
323 • --stats
325 With –ifile print stats at exit. No other output.
326 • --onlyaddr
328 Show only ICAO addresses (testing purposes).
329 • --metric
331 Use metric units (meters, km/h, ...).
332 • --snip <level>
334 Strip IQ file removing samples < level.
335 • --debug <flags>
337 Debug mode (verbose), see README for details.
338 • --help
340 Print usage summary.
341 Debug mode flags:
343 d = Log frames decoded with errors
344 D = Log frames decoded with zero errors
345 c = Log frames with bad CRC
346 C = Log frames with good CRC
347 p = Log frames with bad preamble
348 n = Log network debugging info
349 j = Log frames to frames.js, loadable by debug.html.
350 FILES
352 /usr/share/dump1090/gmap.html
353 dump1090(1)
